接口文档（Swagger / Knife4j / JApiDocs）

接口文档工具概述

为什么要接口文档

在前后端分离架构和微服务盛行的当下，API（Application Programming Interface）是系统间通信的桥梁。接口文档承担着以下核心职责：

契约约定：前端与后端、服务与服务之间以文档为契约，明确请求/响应结构、参数约束、状态码含义。
协作提效：后端开发者提供文档，前端/客户端开发者据此对接，无需反复口头沟通。
测试与调试：清晰的文档可直接用于接口测试工具（如 Postman、curl），降低验证成本。
交接与维护：人员变动时，完善的文档是知识传承的重要载体；系统演进时，文档记录变更历史。

缺乏规范接口文档的团队常面临：前端等待后端"口述"接口、联调阶段频繁修改参数、上线后出现因参数理解不一致导致的 Bug。

传统文档 vs 自动化文档

维度	传统文档（Word / Wiki / Markdown）	自动化文档（Swagger / JApiDocs）
维护方式	人工编写、手动更新	从代码注解或注释自动生成
同步性	极易与代码脱节（代码改而文档不改）	与代码强绑定，文档即代码
实时性	需额外通知变更	启动服务即可查看最新文档
交互性	纯静态文本	提供在线 Try-it-out、调试面板
团队要求	依赖开发者的文档自觉性	工具约束，接入即生效

自动化文档工具的核心价值在于消除信息差——将文档的维护成本嵌入到编码阶段，使文档成为开发的副产品而非额外负担。

Swagger / OpenAPI

OpenAPI 规范

OpenAPI 规范（原名 Swagger Specification）是 Linux 基金会旗下的 RESTful API 描述标准，使用 JSON 或 YAML 格式定义 API 的端点、参数、请求/响应结构、认证方式等。

OpenAPI 3.0 vs 2.0（Swagger）

对比维度	OpenAPI 2.0（Swagger 2.0）	OpenAPI 3.0
根对象	`swagger: '2.0'`	`openapi: '3.0.0'`
请求体	使用 `body` 参数 + `in: body`	独立的 `requestBody` 对象
响应描述	`responses` 中内联 schema	支持 `$ref` 引用 + `content` 分离
多内容类型	仅 `consumes / produces` 全局声明	每个 `requestBody / response` 独立指定
认证	`securityDefinitions` + `security`	`components/securitySchemes` + `security`
Cookie 参数	不支持	支持 `in: cookie`
可复用组件	分散的定义方式	统一的 `components` 容器

OpenAPI 3.0 YAML 示例：

yaml

openapi: 3.0.0
info:
  title: 用户管理 API
  version: 1.0.0
  description: 提供用户注册、登录、信息查询等接口
paths:
  /api/users/{id}:
    get:
      summary: 根据 ID 获取用户信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

Swagger 注解

Swagger 提供一组 Java 注解，用于在代码中描述 API 的元数据。最常用的注解如下：

注解	作用范围	说明
`@Api`	类	描述 Controller 类的用途
`@ApiOperation`	方法	描述单个接口的功能
`@ApiParam`	参数	描述方法参数的含义、是否必填
`@ApiModel`	实体类	描述模型类的用途
`@ApiModelProperty`	字段	描述模型字段的含义、示例值
`@ApiResponses`	方法	聚合多个 `@ApiResponse`
`@ApiResponse`	方法	描述特定响应码的含义
`@ApiIgnore`	类/方法/参数	隐藏接口或参数，不在文档中显示

注：以上注解来自 io.swagger:swagger-annotations 包（Swagger 2.0）。OpenAPI 3.0 对应的注解位于 io.swagger.core.v3:swagger-annotations 包，命名类似：@Tag（替代 @Api）、@Operation（替代 @ApiOperation）、@Schema（替代 @ApiModel）等。

完整注解示例：

java

@RestController
@Api(tags = "用户管理")
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "查询用户信息", notes = "根据用户主键 ID 查询用户的详细信息")
    @ApiResponses({
        @ApiResponse(code = 200, message = "查询成功"),
        @ApiResponse(code = 404, message = "用户不存在")
    })
    public Result<UserVO> getUser(
            @ApiParam(value = "用户 ID", required = true, example = "1001")
            @PathVariable Long id) {
        return Result.success(userService.getById(id));
    }

    @PostMapping
    @ApiOperation(value = "创建用户", notes = "注册新用户并返回用户 ID")
    public Result<Long> createUser(
            @ApiParam(value = "用户信息", required = true)
            @RequestBody @Valid UserCreateDTO dto) {
        return Result.success(userService.create(dto));
    }
}

java

@ApiModel(value = "用户创建请求体")
public class UserCreateDTO {

    @ApiModelProperty(value = "用户名", required = true, example = "zhangsan")
    private String username;

    @ApiModelProperty(value = "邮箱", required = true, example = "zhangsan@example.com")
    private String email;

    @ApiModelProperty(value = "密码（至少 6 位）", required = true, example = "123456")
    private String password;
}

springdoc-openapi 配置

随着 Spring Boot 3.x 的发布，官方推荐的 Swagger 集成方案从 springfox 迁移至 springdoc-openapi。springdoc 原生支持 Spring Boot 3.x / Spring 6.x / Jakarta EE，整合了 OpenAPI 3.0 规范。

Maven 依赖

xml

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

对于 WebFlux 项目：

xml

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.6.0</version>
</dependency>

application.yml 配置

yaml

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha
  packages-to-scan: com.example.project.controller
  paths-to-match: /api/**

编程式配置 OpenAPI 信息

java

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("用户中心 API")
                        .version("1.0.0")
                        .description("提供用户注册、登录、权限管理等核心能力")
                        .contact(new Contact()
                                .name("后端团队")
                                .email("backend@example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0")))
                .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
                .components(new Components()
                        .addSecuritySchemes("BearerAuth",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));
    }
}

分组文档

当单体应用包含多模块（如用户模块、订单模块、支付模块）时，可以将 API 文档按组拆分：

yaml

springdoc:
  group-configs:
    - group: 用户管理
      paths-to-match: /api/users/**
      packages-to-scan: com.example.project.user
    - group: 订单管理
      paths-to-match: /api/orders/**
      packages-to-scan: com.example.project.order
    - group: 支付管理
      paths-to-match: /api/payment/**
      packages-to-scan: com.example.project.payment

启动后分别通过 /v3/api-docs/{group} 获取各组 OpenAPI 定义，Swagger UI 顶部下拉框切换分组。

与 Spring Security 集成

当项目中引入 Spring Security 时，需要放行 Swagger 相关路径：

java

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(
                    "/swagger-ui/**",
                    "/v3/api-docs/**",
                    "/swagger-ui.html"
                ).permitAll()
                .anyRequest().authenticated()
            );
        return http.build();
    }
}

Knife4j

Swagger 增强 UI

Knife4j 是国产开源项目，基于 Swagger 的 v2/api-docs 或 OpenAPI 3 的 /v3/api-docs 接口，提供一套功能更强大、界面更美观的 UI 展示层。它并非替代 Swagger，而是增强 Swagger 的文档呈现和交互体验。

核心增强特性：

现代化 UI：基于 Vue + Ant Design 重构，摒弃 Swagger 原生 UI 的简陋风格
文档管理分组：支持自定义分组、排序、标签管理
全局参数：一次性设置全局 Header / Token，所有接口自动携带
离线文档导出：一键导出 Markdown、HTML、Word、PDF 格式
接口调试增强：请求参数缓存、响应格式化、自定义请求头
I18n 国际化：内置中英文切换

Maven 依赖

xml

<!-- Spring Boot 3.x / Jakarta -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

xml

<!-- Spring Boot 2.x / javax -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

application.yml 配置

yaml

knife4j:
  enabled: true
  setting:
    language: zh-CN
    enable-footer: false
    enable-dynamic-parameter: true
    enable-swagger-models: true
    swagger-model-name: 实体类列表
  documents:
    - name: 接口说明
      locations: classpath:docs/api-overview.md

「文档管理」分组

Knife4j 允许在 UI 侧对接口进行二次分组和排序，而不需要改动后端代码的分组配置。配合 @ApiSupport 和 @ApiSort 注解可实现更精细的控制。

全局参数

在 Knife4j UI 中可以为所有接口统一设置认证 Token 或公共请求头，避免逐个接口填写：

对应后端配置方式：

java

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components()
                    .addParameters("globalHeader", new Parameter()
                            .in("header")
                            .name("X-Request-Id")
                            .description("全局请求追踪 ID")
                            .required(false)
                            .schema(new StringSchema())));
}

增强注解

Knife4j 提供了数个增强注解，弥补 Swagger 原生注解在排序、作者、外部文档等方面的不足：

java

@RestController
@Api(tags = "订单管理")
@ApiSupport(author = "张三", order = 1)  // Knife4j：设置作者和排序
public class OrderController {

    @GetMapping("/list")
    @ApiOperation(value = "订单列表")
    @ApiOperationSupport(order = 1)       // Knife4j：方法级别排序
    @ApiSupport(author = "李四")           // 可覆盖类级别的作者
    public Result<List<OrderVO>> list(
            @ApiParam("页码") @RequestParam Integer page,
            @ApiParam("每页条数") @RequestParam Integer size) {
        return Result.success(orderService.list(page, size));
    }
}

注解	作用	使用位置
`@ApiSupport`	设置作者(author)、排序(order)	类/方法
`@ApiOperationSupport`	方法排序(order)、忽略参数(ignoreParameters)	方法
`@DynamicParameter`	动态表单参数（KV 结构）	方法参数

离线文档导出

Knife4j 提供了一键导出离线文档的能力，可通过 UI 界面操作，也支持编程式导出：

java

// 编程式导出 Markdown 文档
@Autowired
private OpenApiExportService exportService;

public void exportMarkdown(HttpServletResponse response) {
    exportService.exportMarkdown("用户中心 API 文档", response);
}

支持的导出格式：

Markdown：适合 Git 仓库管理、与代码一同版本控制
HTML：可直接部署到内网文档站点
Word：适合交付给非技术团队或客户
PDF：适合打印、归档

JApiDocs

基于注释生成文档（无需注解）

JApiDocs 是一个国产的 API 文档生成工具，其核心理念是零注解侵入——它通过解析 Java 源代码中的 Javadoc 注释和类型信息来推断 API 的定义，无需添加任何 Swagger 注解。

Maven 依赖

xml

<dependency>
    <groupId>io.github.yedaxia</groupId>
    <artifactId>japidocs</artifactId>
    <version>1.4.4</version>
</dependency>

快速入门

java

// 在 main 方法或测试中执行
DocsConfig config = new DocsConfig();
config.setProjectPath("src/main/java");          // 源码路径
config.setProjectName("用户中心");                 // 项目名称
config.setApiVersion("V1.0");                    // API 版本
config.setDocsPath("src/main/resources/docs");   // 文档输出路径
config.setAutoGenerate(Boolean.TRUE);            // 自动生成
Docs.buildHtmlDocs(config);                      // 生成 HTML 文档

JApiDocs 通过解析以下内容自动推断接口信息：

信息来源	解析内容	示例
Javadoc 类注释	接口模块名称	`/** 用户管理控制器 */`
Javadoc 方法注释	接口功能描述	`/** 根据用户 ID 查询用户信息 */`
Javadoc 参数注释	参数说明	`@param userId 用户 ID`
Javadoc 字段注释	字段说明	`/** 用户名 */ private String name;`
方法签名	请求方法、路径	`@GetMapping("/{id}")`
参数类型	数据类型、是否必填	`@RequestParam(required = false)`
返回值类型	响应结构	`Result<UserVO>`

实际代码示例（无需任何 Swagger 注解）：

java

/**
 * 用户管理控制器
 */
@RestController
@RequestMapping("/api/users")
public class UserController {

    /**
     * 查询用户信息
     *
     * @param userId 用户 ID
     * @return 用户详细信息
     */
    @GetMapping("/{userId}")
    public Result<UserVO> getUserInfo(@PathVariable Long userId) {
        return Result.success(userService.getById(userId));
    }

    /**
     * 创建用户
     *
     * @param dto 用户创建信息
     * @return 新创建的用户 ID
     */
    @PostMapping
    public Result<Long> createUser(@RequestBody @Valid UserCreateDTO dto) {
        return Result.success(userService.create(dto));
    }
}

java

/**
 * 用户创建请求体
 */
public class UserCreateDTO {

    /** 用户名 */
    private String username;

    /** 邮箱 */
    private String email;

    /** 密码 */
    private String password;

    // getter / setter 省略
}

生成后的文档目录结构：

docs/
  index.html          # 文档首页
  api/
    user-controller.html  # 用户管理控制器文档
  css/
  js/

对比 Swagger

简易度

维度	JApiDocs	Swagger（springdoc）
额外依赖量	1 个 jar，无运行时依赖	需引入 starter + UI 依赖
注解学习成本	零注解，仅需 Javadoc	需掌握 8+ 个注解
配置复杂度	一段 Java 配置即可	需配置 springdoc + 可能的安全放行
接入时间	5 分钟	15~30 分钟

代码侵入

JApiDocs 主张零侵入——不需要在代码中掺杂任何文档注解，文档信息完全来自标准的 Javadoc 注释。这使得：

代码更干净，业务逻辑与文档描述天然分离
替换文档工具时无需修改业务代码
不增加编译期或运行期注解处理的开销

Swagger 注解则直接嵌入到 Controller 代码中，虽提升了文档表达能力，但也让代码中混入了与业务无关的元数据。

功能丰富度

功能	JApiDocs	Swagger
在线调试（Try-it-out）	❌ 仅离线 HTML	✅ 内置 Swagger UI
请求/响应示例生成	✅ 自动推断	✅ 可自定义
参数约束描述	⚠️ 部分支持（需注释写明）	✅ @ApiParam 明确标注
响应码描述	⚠️ 需在注释中说明	✅ @ApiResponse 注解
分组文档	⚠️ 手动配置多项目	✅ 原生支持分组
OpenAPI 规范导出	❌ 导出 HTML / Markdown	✅ 导出 JSON / YAML
认证配置	❌ 不支持	✅ SecurityScheme 配置

JApiDocs 的优势在于快速接入、低维护成本，适合中小型项目或对文档要求不那么复杂的场景。Swagger 则凭借完善的功能生态，成为大型企业和复杂项目的首选。

对比表

Swagger vs Knife4j vs JApiDocs

对比维度	Swagger（springdoc）	Knife4j	JApiDocs
定位	OpenAPI 规范实现 + 默认 UI	Swagger UI 增强替代	纯离线文档生成器
注解依赖	需要 Swagger 注解	基于 Swagger 注解 + 自有增强注解	无需注解，基于 Javadoc
运行时依赖	是（嵌入应用，启动后访问）	是（嵌入应用）	否（编译期生成，无运行时）
UI 美观度	⭐⭐⭐ 原生 UI 较简陋	⭐⭐⭐⭐⭐ 现代化 UI，功能丰富	⭐⭐ 简单静态 HTML
在线调试	✅ 支持	✅ 支持，增强版调试面板	❌ 不支持
离线文档导出	❌ 需第三方工具	✅ Markdown / HTML / Word / PDF	✅ HTML / Markdown
分组管理	✅ 原生支持	✅ 增强分组 + 排序	⚠️ 手动配置
全局参数	⚠️ 需自定义配置	✅ UI 一键设置	❌ 不支持
代码侵入性	高（注解嵌入代码）	高（需 Swagger 注解 + Knife4j 注解）	低（仅需 Javadoc）
OpenAPI 导出	✅ JSON / YAML	✅ JSON / YAML	❌ 不支持
社区活跃度	⭐⭐⭐⭐⭐ 全球主流	⭐⭐⭐⭐ 国内活跃	⭐⭐ 维护频率较低
学习成本	中	中（需先了解 Swagger）	低
适用场景	中大型项目、需在线调试	中大型项目、追求 UI 和体验	中小型项目、快速接入

选型建议

团队习惯 Swagger 生态 + 需要在线调试 → 直接使用 springdoc-openapi + Swagger UI
追求 UI 美观和团队协作体验 → springdoc-openapi + Knife4j（最推荐组合）
项目小、不想引入额外注解、仅需静态文档 → JApiDocs
既要在线调试又要离线导出 → Knife4j（一体解决）
对外提供 OpenAPI 规范供客户端工具消费 → Swagger（标准 OpenAPI 3.0）

最佳实践

API 文档规范建议

1. 注释即文档，养成习惯

不论使用哪种工具，高质量的注释是高质量文档的基础。建议团队制定注释规范：

java

/**
 * 分页查询用户列表
 *
 * <p>支持按用户名模糊搜索、按状态筛选，结果按创建时间倒序排列。</p>
 * <p>权限要求：需要 ADMIN 或 MANAGER 角色。</p>
 *
 * @param page     页码，从 1 开始
 * @param size     每页条数，最大 100
 * @param keyword  搜索关键词（可选，模糊匹配用户名和邮箱）
 * @param status   用户状态（可选：ACTIVE / INACTIVE / LOCKED）
 * @return 分页结果，包含用户列表和总记录数
 */
@GetMapping("/page")
public Result<PageResult<UserVO>> pageUsers(
        @RequestParam @Min(1) Integer page,
        @RequestParam @Range(min = 1, max = 100) Integer size,
        @RequestParam(required = false) String keyword,
        @RequestParam(required = false) UserStatus status) {
    return Result.success(userService.pageUsers(page, size, keyword, status));
}

2. 统一响应结构

定义全局统一的响应体，让文档中的响应结构保持一致：

java

@ApiModel(value = "统一响应体")
public class Result<T> {

    @ApiModelProperty(value = "业务状态码，200 表示成功", example = "200")
    private int code;

    @ApiModelProperty(value = "提示信息", example = "操作成功")
    private String message;

    @ApiModelProperty(value = "响应数据")
    private T data;

    // 静态工厂方法
    public static <T> Result<T> success(T data) {
        return new Result<>(200, "操作成功", data);
    }

    public static <T> Result<T> error(int code, String message) {
        return new Result<>(code, message, null);
    }
}

3. 枚举类型标准化

对枚举字段提供清晰的文档说明，避免对接方猜测取值：

java

@ApiModel(value = "用户状态")
public enum UserStatus {

    @ApiModelProperty("正常")
    ACTIVE,

    @ApiModelProperty("已停用")
    INACTIVE,

    @ApiModelProperty("已锁定")
    LOCKED
}

4. 接口命名与分组

Controller 类名建议使用领域名词复数（UserController、OrderController）
方法命名体现 HTTP 语义（get / create / update / delete / page）
利用 @Api(tags = "...") 按模块分组（用户管理、订单管理、支付管理）
避免将多个业务领域放在同一个 Controller 中

版本管理

API 文档应与代码版本保持同步，常见策略如下：

策略一：文档嵌入应用

文档（Swagger UI / Knife4j UI）随应用一起部署，访问 {host}:{port}/swagger-ui.html 即可查看对应版本的文档。这是最常用也最推荐的方式：

每个版本的代码对应专属文档
部署即查看，无需额外维护文档站点
适合微服务架构，每个服务独立暴露文档

策略二：文档纳入版本控制

将离线文档（Knife4j 导出的 Markdown 或 JApiDocs 生成的 HTML）提交到 Git 仓库，随代码一同评审：

bash

docs/
  api/
    v1.0.0/
      user-api.md
      order-api.md
    v1.1.0/
      user-api.md
      order-api.md

策略三：独立文档站

使用 springdoc-openapi 导出 OpenAPI JSON 文件，接入文档管理平台（如 YApi、SwaggerHub、Rap2）：

bash

# 构建时导出 OpenAPI 规范
curl http://localhost:8080/v3/api-docs -o openapi.json

接口变更通知

API 变更时及时通知上下游至关重要，可结合以下实践：

1. 语义化版本号

遵循 Semantic Versioning，在 API 路径中体现版本：

/api/v1/users        # 稳定版
/api/v2/users        # 新版本（破坏性变更）

2. Controller 级别标记版本

java

@Api(tags = "用户管理 v2")
@ApiSupport(author = "后端团队")
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    // ...
}

3. 变更日志集成

Knife4j 支持在文档中嵌入变更说明：

yaml

knife4j:
  documents:
    - name: 更新日志
      locations: classpath:docs/changelog.md

4. Git Hooks + CI 集成

在 CI/CD 流水线中检测 API 变更并触发通知：

比较当前分支与目标分支的 OpenAPI JSON 差异
若有变更，自动在 Merge Request 评论中列出变更摘要
通过飞书/钉钉/企业微信机器人推送变更通知

5. @deprecated 标记

对即将废弃的接口使用 @Deprecated 注解并在文档中标记：

java

@Deprecated
@ApiOperation(value = "【即将废弃】旧版用户注册接口，请使用 /api/v2/users/register")
@PostMapping("/register")
public Result<Long> registerV1(@RequestBody @Valid UserCreateDTO dto) {
    return Result.success(userService.create(dto));
}

在 OpenAPI 中对应 deprecated: true 字段，Knife4j UI 会以特殊样式标记已弃用接口。

接口文档（Swagger / Knife4j / JApiDocs） ​

接口文档工具概述 ​

为什么要接口文档 ​

传统文档 vs 自动化文档 ​

Swagger / OpenAPI ​

OpenAPI 规范 ​

OpenAPI 3.0 vs 2.0（Swagger） ​

Swagger 注解 ​

springdoc-openapi 配置 ​

Maven 依赖 ​

application.yml 配置 ​

编程式配置 OpenAPI 信息 ​

分组文档 ​

与 Spring Security 集成 ​

Knife4j ​

Swagger 增强 UI ​

Maven 依赖 ​

application.yml 配置 ​

「文档管理」分组 ​

全局参数 ​

增强注解 ​

离线文档导出 ​

JApiDocs ​

基于注释生成文档（无需注解） ​

Maven 依赖 ​

快速入门 ​

对比 Swagger ​

简易度 ​

代码侵入 ​

功能丰富度 ​

对比表 ​

Swagger vs Knife4j vs JApiDocs ​

选型建议 ​

最佳实践 ​

API 文档规范建议 ​

1. 注释即文档，养成习惯 ​

2. 统一响应结构 ​

3. 枚举类型标准化 ​

4. 接口命名与分组 ​

版本管理 ​

策略一：文档嵌入应用 ​

策略二：文档纳入版本控制 ​

策略三：独立文档站 ​

接口变更通知 ​

1. 语义化版本号 ​

2. Controller 级别标记版本 ​

3. 变更日志集成 ​

4. Git Hooks + CI 集成 ​

5. @deprecated 标记 ​

接口文档（Swagger / Knife4j / JApiDocs）

接口文档工具概述

为什么要接口文档

传统文档 vs 自动化文档

Swagger / OpenAPI

OpenAPI 规范

OpenAPI 3.0 vs 2.0（Swagger）

Swagger 注解

springdoc-openapi 配置

Maven 依赖

application.yml 配置

编程式配置 OpenAPI 信息

分组文档

与 Spring Security 集成

Knife4j

Swagger 增强 UI

Maven 依赖

application.yml 配置

「文档管理」分组

全局参数

增强注解

离线文档导出

JApiDocs

基于注释生成文档（无需注解）

Maven 依赖

快速入门

对比 Swagger

简易度

代码侵入

功能丰富度

对比表

Swagger vs Knife4j vs JApiDocs

选型建议

最佳实践

API 文档规范建议

1. 注释即文档，养成习惯

2. 统一响应结构

3. 枚举类型标准化

4. 接口命名与分组

版本管理

策略一：文档嵌入应用

策略二：文档纳入版本控制

策略三：独立文档站

接口变更通知

1. 语义化版本号

2. Controller 级别标记版本

3. 变更日志集成

4. Git Hooks + CI 集成

5. @deprecated 标记