整合 Swagger

Swagger 介绍

官网：https://swagger.io/

Swagger是一个接口文档生成工具，同时提供接口测试调用的辅助功能。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。

Swagger的优点:

  • 号称世界上最流行的API框架
  • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
  • 直接运行，在线测试API
  • 支持多种语言 （如：Java，PHP等）

swagger3.0说明:

  • swagger3.0迭代算是重大更新。
    一个是添加了 starter，依赖用springfox-boot-starter这一个就可以了。具体的可以alt+insert自己搜这个。

  • ui界面移动到了/swagger-ui/index.html，也就是可以只打/swagger-ui/ 接口看起来也正常了点
    configure的启动标签那边变成了**@EnableOpenApi**

  • 使用swagger3出现Failed to start bean‘documentationPluginsBootstrapper 错误

    • 可以在application.properties里面加spring.mvc.pathmatch.matching-strategy= ANT_PATH_MATCHER，可以解决问题
    • 降低springboot版本为 2.5.6, 也可以解决问题

Swagger常用注解

Swagger注解 简单说明
@Api(tags = "xxx模块说明") 作用在模块类上
@ApiOperation("xxx接口说明") 作用在接口方法上
@ApiModel("xxxPOJO说明") 作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true) 作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明") 作用在参数、方法和字段上，类似@ApiModelProperty

整合Swagger

  1. 在pom.xml加入所需依赖(Swagger 版本可执行更换)

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <!-- swagger 接口文档 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

  2. 在项目的的config配置中创建SwaggerConfig

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    @Configuration
    @EnableSwagger2
    @Profile({"dev", "test"})   //版本控制访问
    public class SwaggerConfig {
        @Bean
        public Docket docket() {
            // 创建一个 swagger 的 bean 实例
            return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 配置扫描指定包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.xiaoyu.controller"))
                .paths(PathSelectors.any())
                .build();
        }
        
        /**
         * api信息
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("伙伴匹配系统-接口文档") // 标题
                    .description("小鱼伙伴匹配系统-接口文档") // 描述
                    .termsOfServiceUrl("https://github.com/xiaoguiyu") // 跳转连接
                    .version("1.0") // 版本
                    .contact(new Contact("xiaoyu", "https://github.com/xiaoguiyu", "lin802366@gmail.com"))
                    .version("1.0")
                    .build();
        }
    }

  3. 在application.yaml中添加配置

    1
    2
    3
    4
    spring:
      mvc:
        pathmatch:
          matching-strategy: ant_path_matcher

  4. 启动项目, swagger访问地址 http://localhost:8080/api/swagger-ui.html

整合 Knife4j

Knife4j介绍

Knife4j是对Swagger文档的增强解决方案，底层是对Springfox的（boot整合swagger）的封装，是对接口文档UI进行优化，注解与Swagger相同

核心功能

  • 文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，对该接口的使用情况一目了然。

  • 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、响应时间、响应状态码等信息，帮助开发者在线调试。

  1. 在pom.xml 引入所需依赖

    1
    2
    3
    4
    5
    6
    <!-- knife4j 接口文档 -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.7</version>
    </dependency>

  2. 在项目的的config配置中创建SwaggerConfig

    此处要千万注意: 线上环境不要把接口暴露出去！！！

    可以在SwaggerConfig 配置文件开头加上 :

    @Profile({"dev", "test"}) 限定配置仅在部分环境开启

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    @Configuration
    @EnableSwagger2
    @Profile({"dev", "test"})   //版本控制访问
    public class SwaggerConfig {
        @Bean
        public Docket docket() {
            // 创建一个 swagger 的 bean 实例
            return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 配置扫描指定包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.xiaoyu.controller"))
                .paths(PathSelectors.any())
                .build();
        }
        
        /**
         * api信息
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("伙伴匹配系统-接口文档") // 标题
                    .description("小鱼伙伴匹配系统-接口文档") // 描述
                    .termsOfServiceUrl("https://github.com/xiaoguiyu") // 跳转连接
                    .version("1.0") // 版本
                    .contact(new Contact("xiaoyu", "https://github.com/xiaoguiyu", "lin802366@gmail.com"))
                    .version("1.0")
                    .build();
        }
    }

  3. 在application.yaml中添加配置

    1
    2
    3
    4
    spring:
      mvc:
        pathmatch:
          matching-strategy: ant_path_matcher

  4. 启动项目, swagger访问地址 http://localhost:8080/api/doc.html