专栏首页BAT的乌托邦【小家Spring】借助Springfox整合SpringBoot和Swagger(API接口神器)

【小家Spring】借助Springfox整合SpringBoot和Swagger(API接口神器)

版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。

本文链接:https://blog.csdn.net/f641385712/article/details/84064122

背景

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远

前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。

没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏(其实相比于Swagger,都不好)。

书写API文档的工具有很多,但是能称之为“框架”的,估计也只有swagger了。

swagger的生态使用图

Springfox解释

swagger是一个流行的API开发框架,这个框架以“开放API声明”(OpenAPI Specification,OAS)为基础,对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,几乎支持所有语言)。

由于Spring的流行,Marty Pitt编写了一个基于Spring的组件swagger-springmvc,用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来,同时springfox也是一个新的项目,本文仍然是使用其中的一个组件springfox-swagger2。

pringfox-swagger2依然是依赖OSA规范文档,也就是一个描述API的json文件,而这个组件的功能就是帮助我们自动生成这个json文件,我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来,用一种更友好的方式呈现出来。

Swagger是一款 RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful风格的Web服务,加上 swagger-ui,可以有很好的呈现。

与SpringBoot集成的步骤

第一步:导入依赖(本文采用SpringBoot2+springfox2.9.2版本)

		<-- boot相关依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

		<!--整合swagger-->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

第二步:书写SwaggerConfig配置文件

/**
 * @author fangshixiang
 * @description
 * @date 2018-11-14 10:48
 */
@EnableSwagger2 //开启springfox的Swagger2
@Configuration
//@Profile("dev") //只有在测试环境才开启Swagger
public class SwaggerConfig {

    //是否开启swagger,正式环境一般是需要关闭的,可根据springboot的多环境配置进行设置
    //若配置类上写了使用了@Profile 也可以达到类似效果 二选一 此处默认值为true
    @Value(value = "${swagger.enable:true}")
    private Boolean swaggerEnable;

    /**
     * 创建一个Docket 并且注册到Spring容器里即可完成配置
     *
     * @return Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //是否开启
                .enable(swaggerEnable)
                //设置API描述信息
                .apiInfo(apiInfo())
                .select()
                //扫描的的包 一般定位到controller那即可(若有接口层,此处报名需要注意)
                .apis(RequestHandlerSelectors.basePackage("com.fsx.run2.controller"))
                // 指定路径处理:PathSelectors.any()代表所有的路径
                // 也可以指定某些接口不要对外暴露 这里定义一些规则就行 如正则表达式
                .paths(PathSelectors.any())
                .build()
                //base,最终调用接口后会和paths拼接在一起
                .pathMapping("/");
    }

    //设置API信息 一些简单的描述信息而已
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API Document for 自定义服务名")
                .description("API描述信息")
                .contact(new Contact("Fangshixiang", "https://www.baidu.com", "shixiangfang@aliyun.com"))
                .version("1.0.0")
                .build();
    }

}

第三步:书写测试的Controller类

@RestController
@RequestMapping("/demo")
@Api(tags = "Demo API接口文档")
public class DemoController {

    @ApiOperation("根据id获取一条记录")
    @GetMapping("/{id}")
    Object getById(@PathVariable Integer id) {
        return id;
    }

}

最后,启动项目,访问:http://localhost:8080/swagger-ui.html

这样,API文档就自动生成了,我们只需要把这个连接发给前端,前端就能对API接口的相关数据结构一目了然,体验非常好

强烈建议在生产环境关闭 swagger,避免不必要的漏洞暴露!

Springfox简单原理

在前言中,我们知道,我们的第一个任务就是生成一个满足OSA规范的json文件(当然,创建一个spring的项目就不说了)。对于这个任务,springfox为我们提供了一个Docket(摘要的意思)类,我们需要把它做成一个Bean注入到spring中,显然,我们需要一个配置文件,并通过一种方式(显然它会是一个注解)告诉程序,这是一个Swagger配置文件。

这就是Springfox的强大之处,他启动时候回去扫描包下的controller,然后组装成json,然后放在内存里。最后提供UI界面直接访问即可,非常方便。

Swagger其余小组件介绍

swagger-editor(需要单独安装在操作系统上,使用较少)

就是一个在线编辑文档说明文件(swagger.json或swagger.yaml文件)的工具,以方便生态中的其他小工具(swagger-ui)等使用。 左边编辑,右边立马就显示出编辑内容来。

swagger-codegen

代码生成器,脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。 有一定用处,Java系用的挺多。 对于从来不喜欢自动生成代码的我,觉得鸡肋

swagger-validator

这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单,只需url地址栏,根路径下加上一个参数url,参数内容是放swagger说明文件的地址。即可校验。

最后

Swagger在分布式环境下,可以结合网关聚合API文档,具体参考: 利用swagger2聚合API文档 聚合API文档在开放过程中,可以大大提高效率,值得推荐

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 3种方式实现多数据源控制/切换、实现读写分离;演示借助AbstractRoutingDataSource实现多数据源的动态切换代码【享学Spring】

    什么时候一个Java工程里需要同时控制(连接)多个数据源呢?我认为主要有如下两种情况:

    YourBatman
  • 【小家Java】你真的了解Java泛型参数吗?细说java.lang.reflect.Type(ParameterizedType、TypeVariable、WildcardType...)

    咋一看标题,你可能会说。不就是泛型吗,平时都使用着呢,没什么难的吧。 感觉了解了,但是真正的深入才知道自己了解甚少!

    YourBatman
  • 【小家java】Java之Apache Commons-Collections4使用精讲(Bag、Map、List、Set全覆盖)

    虽然JDK提供给我们的集合框架已经足够强大,基本能解决我们平时的绝大所述问题,并且效率还挺高。

    YourBatman
  • 5分钟了解swagger

    landv
  • 5分钟了解swagger

    随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。

    互扯程序
  • Swagger-UI

    顾翔老师开发的bugreport2script开源了,希望大家多提建议。文件在https://github.com/xianggu625/bug2testscr...

    小老鼠
  • 简化Swagger使用的自制Starter:spring-boot-starter-swagger,欢迎使用和吐槽

    项目简介 该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档,简化原生使用swag...

    程序猿DD
  • spring-boot-starter-swagger迎新伙伴支持,加速更新进度(1.3.0.RELEASE)

    从该starter创建至今收到了不少使用反馈,同时也有不错的童鞋申请加入一起维护。本篇先欢迎小火童鞋的加入及贡献,接下来具体说说本次的更新内容。 本次更新主要新...

    程序猿DD
  • SpringBoot结合swagger2快速生成简单的接口文档

    经我多次尝试application.properties中不加任何swagger配置也可生成文档进行正常测试

    道可道非常道
  • 基于SpringCloud的Microservices架构实战案例-在线API管理

    前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。 本实战...

    歪脖贰点零

扫码关注云+社区

领取腾讯云代金券