后端整合 Swagger + Knife4j 接口文档

什么是接口文档？写接口信息的文档，每条接口包括：

• 请求参数
• 响应参数
  • 错误码
• 接口地址
• 接口名称
• 请求类型
• 请求格式
• 备注

为什么需要接口文档？

• 有个书面内容（背书或者归档），便于大家参考和查阅，便于 维护
• 接口文档便于前端和后端开发对接，前后端联调的 介质 。后端 => 接口文档 <= 前端
• 好的接口文档支持在线调试、在线测试，可以作为工具提高我们的开发测试效率

怎么做接口文档？

• 手写（比如腾讯文档、Markdown 笔记）
• 自动化接口文档生成：自动根据项目代码生成完整的文档或在线调试的网页。如Swagger，Postman（侧重接口管理）（国外）；apifox、apipost、eolink（国产）

操作：

1. 引入依赖

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>2.0.7</version>
</dependency>

2. 编写配置类

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
    @Bean(value = "defaultApi2")
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private  ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("标题")
                .description("描述")
                .termsOfServiceUrl("网址")
                .contact(new Contact("联系"))
                .version("版本")
                .build();
    }
}

3. 如果 springboot version >= 2.6，需要添加如下配置：

mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4. 查看页面
   http://localhost:8080/api/doc.html#/home
   对应服务端口的

5. 防止上线后别人看到自己的接口
   SwaggerConfig 配置文件开头加上 @Profile({"dev", "test"})
   可以在对应的环境开放api

Swagger 原理：

1. 引入依赖（Swagger 或 Knife4j：https://doc.xiaominfo.com/knife4j/documentation/get_start.html）
2. 自定义 Swagger 配置类
3. 定义需要生成接口文档的代码位置（Controller）
4. 千万注意：线上环境不要把接口暴露出去！！！可以通过在 SwaggerConfig 配置文件开头加上 @Profile({"dev", "test"}) 限定配置仅在部分环境开启
5. 启动即可
6. 可以通过在 controller 方法上添加 @Api、@ApiImplicitParam(name = “name”,value = “姓名”,required = true) @ApiOperation(value = “向客人问好”) 等注解来自定义生成的接口描述信息