一、背景

前后台分离架构下，后端主要提供 Restful API 给前端和 APP 使用。 如果自己写文档说明 Request、Response 协议格式，费时耗力，并且跟单元测试一样需要持续维护保持最新。

API 文档管理业界使用 Swagger UI（https://swagger.io/tools/swagger-ui/）。本文推荐的 Knife4j（https://doc.xiaominfo.com/docs/action/springboot）正是基于 Swagger。

swagger-ui

二、如何使用

Spring Boot 2 的版本参考：https://doc.xiaominfo.com/docs/action/springboot

接入比较简单，注意配置中生成 Docket。线下启用，线上关闭。

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
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled}")
    private Boolean enabled;

    @Bean
    @SuppressWarnings("all")
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enabled)
                .pathMapping("/")
                .apiInfo(apiInfo())
                .select()
                .paths(PathSelectors.regex("^(?!/error).*"))
                .paths(PathSelectors.any())
                .build()
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .description("XXX 系统API文档")
                .title("XXX系统接口文档")
                .version("2.6")
                .build();
    }
}

为什么不直接使用 swagger-ui 而是要选择 Knifej？

个人觉得 swagger-ui 满足我们大部分需求，它会把 @RestController、@RequestMapping、@GetMapping 生成 OpenAPI 规范的文档。使用 Knifej，它增强的地方有：

  1. 加入支持 Spring Boot 的 starter，简化 swagger jar 包的引入
  2. 基础 ui 组件增强(自定义文档、动态参数调试、I18n、接口排序、导出等)

Knifej

三、注意事项

  1. 线上环境谨慎打开该功能，避免服务接口泄露被入侵。因为 swagger-ui 中的 API 链接是可以支持测试调用的，如果没有 Token 或者 Spring Security 保护，会造成 CRUD 的直接调用

  2. swagger-ui 的默认路径为：/swagger-ui.html;Knifej 的默认路径为：/doc.html