一、API接口文档的重要性

目前很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维护一份及时更新且完整的API 文档将会大大的提高我们的工作效率。传统意义上的文档都是后端开发人员使用word编写的，这种方式很难保证文档的及时性，久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，既可以根据代码自动生成 API 文档，也可以通过Swagger UI 直接在文档页面尝试 API 的调用，很好的保证了文档的时效性及开发调试效率。

二、在项目中整合swagger2

2.1通过Maven引入相关类库

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

2.2通过java Config对Swagger2进行配置

@Profile({"dev","test"})
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger文档案例")
                .description("用于演示swagger API文档案例")
                .version("1.0")
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        .select()
                        //扫描basePackage包下面的“/demo/”路径下的内容作为接口文档构建的目标
                        .apis(RequestHandlerSelectors.basePackage("cn.lsp.springboot"))
                        .paths(PathSelectors.regex("/demo/.*"))
                        .build();
    }
}

• @EnableSwagger2 注解表示开启SwaggerAPI文档相关的功能；
• ApiInfo类用于配置接口文档的title(标题)、描述、termsOfServiceUrl（服务协议）、版本等相关信息；
• basePackage表示扫描哪个package下面的Controller类作为API接口文档内容范围；
• paths表示哪一个请求路径下控制器映射方法，作为API接口文档内容范围；

2.3在application.yml中增加配置

如果在配置完swagger后，启动项目过程中报错：Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException，则配置一下内容：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

原因： 这是因为Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。
解决：在application.properties里配置：spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER。

2.4swagger的使用

集成完成之后，启动项目并访问：http://localhost:8080/swagger-ui.html ，如下：

swagger

三、使用swagger注解

我们还可以对swagger自动生成的API文档内容进行修改，使得API文档更具可读性。这就需要在Controller接口上增加Swagger注解来实现。

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性
@ApiIgnore()用于类，方法，方法参数 表示这个方法或者类被忽略

@Api(value = "question open Api Client", description = "试题开放 API", protocols = "application/json")
@RequestMapping("/open-api")
public interface QuestionOpenApi {

    @ApiOperation(value = "获取所有学段", notes = "获取所有学段", nickname = "periods")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true)
    })
    @RequestMapping(value = "/periods", method = RequestMethod.GET)
    List<OpenPeriodDTO> periods();

    @ApiOperation(value = "获取所有学科", notes = "获取所有学科", nickname = "subjects")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "periodId", value = "学段id", paramType = "path", dataType = "string", required = true)
    })
    @RequestMapping(value = "/subjects/{periodId}", method = RequestMethod.GET)
    List<OpenSubjectDTO> subjects(@PathVariable("periodId") String periodId);

    @ApiOperation(value = "获取某科目学科题型", notes = "获取某科目学科题型", nickname = "subjectTypes")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "periodId", value = "学段id", paramType = "query", dataType = "string", required = true),
            @ApiImplicitParam(name = "subjectId", value = "学科id", paramType = "query", dataType = "string", required = true)
    })
    @RequestMapping(value = "/subject-types", method = RequestMethod.GET)
    List<OpenSubjectTypeDTO> subjectTypes(@RequestParam("periodId") String periodId, @RequestParam("subjectId") String subjectId);

    @ApiOperation(value = "获取某科目知识点", notes = "获取某科目知识点", nickname = "points")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "periodId", value = "学段id", paramType = "query", dataType = "string", required = true),
            @ApiImplicitParam(name = "subjectId", value = "学科id", paramType = "query", dataType = "string", required = true)
    })
    @RequestMapping(value = "/points", method = RequestMethod.GET)
    KnowledgePointTreeListDTO points(@RequestParam("periodId") String periodId, @RequestParam("subjectId") String subjectId);

    @ApiOperation(value = "搜索试题", notes = "搜索试题", nickname = "search")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true),
        @ApiImplicitParam(name = "param", value = "参数", paramType = "body", dataType = "ParamQuestionDTO", required = true)
    })
    @RequestMapping(value = "/questions", method = RequestMethod.GET)
    PageableData<QuestionDTO> questions(@RequestBody @Valid ParamQuestionDTO param);
}

Swagger API文档预览图

四、生产环境下禁用swagger

我们的文档通常是在团队内部观看及使用的，不希望发布到生产环境让用户看到。

• 禁用方法1：使用注解@Profile({"dev","test"}) 表示在开发或测试环境开启，而在生产关闭。
• 禁用方法2：使用注解@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") 然后在测试配置或者开发配置中添加 swagger.enable = true 即可开启，生产环境不填则默认关闭Swagger.

五、Swagger3及OpenAPI规范

• OpenAPI是规范的正式名称。规范的开发工作于2015年启动，当时SmartBear（负责Swagger工具开发的公司）将Swagger 2.0规范捐赠给了Open API Initiative，该协会由来自技术领域不同领域的30多个组织组成。此后，该规范被重命名为OpenAPI规范。
• Swagger
  • 是一个 API文档维护组织，后来成为了 Open API 标准的主要定义者。现在最新的版本为17年发布的 Swagger3（Open Api3）。
  • 是一个Open API规范实现工具包，由于Swagger工具是由参与创建原始Swagger规范的团队开发的，因此通常仍将这些工具视为该规范的代名词。目前可以认为Swagger3就是Open API 3.0
• OpenAPI 3.0：2017年7月，Open API Initiative最终发布了OpenAPI Specification 3.0.0。它对2.0规范进行了很多改进。Open API 3.0规范可以用JSON或YAML编写，并且在记录RESTful API方面做得很好。同时标志着Swagger2成为过去式。
• SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。截至2020年4月，尚未支持 OpenAPI3 标准。
• SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。
  也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用

要使用OpenAPI（swagger3），只需在项目的pom.xml中添加如下OpenAPI依赖即可：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.0</version>
</dependency>