bug菌_打造API文档

2024-06-13 | 阅读：

为什么需要API文档

前后端联调、第三方对接，都需要一份接口约定：请求路径、请求方法、参数格式、返回结构、错误码。
手写 Markdown 或 Word 的问题很明显：代码改了，文档忘了改，最后没人再相信文档。

更省事的做法是把接口说明写在代码里，让工具自动生成文档——代码即文档，接口一改文档自动跟着变。
本文用 springdoc-openapi（Swagger UI）和 Knife4j 来实现这一点。

常用工具对比

工具	说明	特点
Swagger UI	OpenAPI 规范的官方展示界面	能在线调试接口，界面英文
springdoc-openapi	Spring Boot 3 推荐的文档生成库	自动扫描 Controller 生成 OpenAPI 描述
Knife4j	国产增强界面，基于 springdoc	中文界面、支持离线文档导出
Apifox / Postman	第三方接口工具	导入 OpenAPI 文件后调试、Mock、生成文档

Spring Boot 3 不要再用 springfox（springfox-swagger2），它已停止维护，与 Boot 3 不兼容。

Spring Boot 整合 springdoc-openapi

一、添加依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

Spring Boot 3 用 springdoc-openapi-starter-webmvc-ui；Spring Boot 2 用 springdoc-openapi-ui（1.7.x）。
这个依赖自带 Swagger UI，不需要再单独引入。

二、配置

在 application.properties 中按需配置（不配也能用，下面是常用项）。

# OpenAPI 描述文件的访问路径
springdoc.api-docs.path=/v3/api-docs
# Swagger UI 的访问路径
springdoc.swagger-ui.path=/swagger-ui.html
# 接口按名称排序
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=alpha

三、启动并访问

启动项目后打开：

描述文件（JSON）：http://localhost:8080/v3/api-docs
文档界面：http://localhost:8080/swagger-ui.html

此时所有 Controller 的接口已经自动列出，可以直接点 “Try it out” 发请求。

四、给接口补充说明

不加注解也能生成文档，但只有路径和方法名，别人看不懂。加注解后才是可读的文档。

@Tag(name = "用户接口", description = "用户的查询与新增")
@RestController
@RequestMapping("/user")
public class UserController {

    @Resource
    private UserService userService;

    @Operation(summary = "根据 id 查询用户", description = "id 不存在时返回 null")
    @GetMapping("/{id}")
    public UserEntity getById(
            @Parameter(description = "用户 id", example = "1") @PathVariable Integer id) {
        return userService.findById(id);
    }
}

实体类上加 @Schema，字段说明会显示在请求和响应示例里。

@Schema(description = "用户信息")
public class UserEntity {

    @Schema(description = "用户 id", example = "1")
    private Integer id;

    @Schema(description = "用户名", example = "lxy")
    private String name;

    // getter / setter 省略
}

常用注解

注解	作用	加在哪里
`@Tag`	给一组接口命名、分组	Controller 类
`@Operation`	描述单个接口的用途	接口方法
`@Parameter`	描述单个参数的含义、示例值	方法参数
`@Schema`	描述实体类或字段	类 / 字段
`@ApiResponse`	描述返回结果和状态码	接口方法
`@Hidden`	在文档中隐藏某个接口或类	方法 / 类

注意区分：@Api、@ApiOperation 是 springfox（Swagger 2）的注解，在 Spring Boot 3 的 springdoc 里要用上面这套。

生成离线文档与导入测试工具

springdoc 生成的是标准 OpenAPI 描述文件，除了给 Swagger UI 用，还可以导出给其他工具。

JSON 格式：http://localhost:8080/v3/api-docs
YAML 格式：http://localhost:8080/v3/api-docs.yaml

保存到本地：

curl http://localhost:8080/v3/api-docs.yaml -o api.yaml

然后在 Apifox、Postman、YApi 里选择“导入 OpenAPI / Swagger 文件”，就能直接联调、生成 Mock 和接口文档，适合交付给前端或第三方。

换成 Knife4j 界面

觉得 Swagger UI 的英文界面不好用，可以换成 Knife4j，它的底层还是 springdoc，生成的内容一样。

一、替换依赖

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

Knife4j 的 starter 已经包含 springdoc，不要再同时引入 springdoc，否则可能出现版本冲突。

二、访问

启动后访问 http://localhost:8080/doc.html：左侧是接口分组，右侧是参数说明和调试区，支持导出离线文档（HTML、Markdown、OpenAPI JSON）。
原来的 /swagger-ui.html 和 /v3/api-docs 依然可用。

注意事项

生产环境关闭：文档会把所有接口和参数结构暴露出去，上线时应关闭。
```
 springdoc.api-docs.enabled=false
 springdoc.swagger-ui.enabled=false
```
有 Spring Security 或拦截器时要放行：/v3/api-docs/**、/swagger-ui/**、/doc.html、/webjars/**，否则文档页打不开或一直 401。
敏感字段不要展示：密码、手机号等字段用 @Schema(hidden = true) 或 @JsonIgnore 隐藏。
注解要与代码同步维护：@Operation、@Parameter 写错比不写更容易误导，改接口时顺手改注解。

行者常至，为者常成！

JHHK