第84章 API文档

课程目录第84章 API文档

第84章 API文档：OpenAPI/Swagger、SpringDoc、API测试工具

说到API文档，我估计不少朋友都经历过这种场景——后端接口写完了，前端跑来问「这个参数是啥类型？」「返回结构长什么样？」。你口头说一遍，他记不住。你写个Word文档，改代码时忘了更新。嗯，这活儿我干过，太痛苦了。

后来我接触到了OpenAPI规范，说白了就是一套标准，用来描述你的RESTful接口。你只要按规范写一个描述文件，工具就能自动生成文档、客户端代码、甚至测试用例。今天我们就聊聊这套东西在Kotlin项目里怎么落地。

OpenAPI与Swagger：别搞混了

很多人把OpenAPI和Swagger当成一回事。其实不是。

OpenAPI：是一个规范（Specification），定义了API描述文件的格式。目前最新是3.1版本。
Swagger：是实现了OpenAPI规范的一套工具集。比如Swagger UI、Swagger Editor、Swagger Codegen。

打个比方：OpenAPI就像HTML标准，Swagger就像Chrome浏览器。标准归标准，工具归工具。

核心要点：你写的是OpenAPI描述文件，Swagger负责把它渲染成漂亮的文档页面。

SpringDoc：Kotlin项目的首选

在Spring Boot项目里，以前大家用Springfox。但我个人习惯用SpringDoc，原因很简单——它对Kotlin的支持更好，而且维护活跃。SpringDoc会自动扫描你的Controller注解，生成OpenAPI 3.0规范的JSON文件。

怎么集成？加个依赖就行：

// build.gradle.kts
implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0")

启动项目后，访问 http://localhost:8080/swagger-ui.html，就能看到自动生成的API文档页面。什么都不用配，开箱即用。

小技巧：如果你用的是WebFlux（响应式栈），把依赖换成 springdoc-openapi-starter-webflux-ui 即可。

给API加上描述信息

光有自动扫描还不够。你想想看，前端同事看到接口路径是 /api/v1/users/{id}，他根本不知道这个id是用户ID还是订单ID。所以我们需要手动补充描述。

SpringDoc支持通过注解来丰富文档。我常用的几个：

注解	作用	示例
`@Operation`	描述接口的用途	`@Operation(summary = "获取用户详情")`
`@Parameter`	描述单个参数	`@Parameter(description = "用户ID，必填")`
`@Schema`	描述数据模型字段	`@Schema(description = "用户邮箱")`
`@ApiResponse`	描述响应状态码和结构	`@ApiResponse(responseCode = "404", description = "用户不存在")`

看一个完整的例子：

@RestController
@RequestMapping("/api/v1/users")
class UserController {

    @Operation(summary = "根据ID获取用户信息")
    @ApiResponses(
        value = [
            ApiResponse(responseCode = "200", description = "成功返回用户"),
            ApiResponse(responseCode = "404", description = "用户未找到")
        ]
    )
    @GetMapping("/{id}")
    fun getUser(
        @Parameter(description = "用户唯一标识")
        @PathVariable id: Long
    ): ResponseEntity<UserResponse> {
        // 业务逻辑...
    }
}

data class UserResponse(
    @Schema(description = "用户ID", example = "1001")
    val id: Long,

    @Schema(description = "用户昵称", example = "张三")
    val nickname: String,

    @Schema(description = "邮箱地址", example = "zhangsan@example.com")
    val email: String
)

这样生成的文档，每个字段都有说明，前端看了直接就能对接。我在项目中遇到过好几次因为参数含义不清导致的返工，加了注解之后，这类问题基本绝迹了。

分组与多版本API

项目大了，接口会分很多组。比如内部API和外部API，或者v1和v2版本。SpringDoc支持分组配置：

# application.yml
springdoc:
  group-configs:
    - group: "用户端接口"
      paths-to-match: "/api/v1/**"
      packages-to-scan: "com.example.controller.user"
    - group: "管理端接口"
      paths-to-match: "/api/admin/**"
      packages-to-scan: "com.example.controller.admin"

启动后，Swagger UI左上角会出现下拉菜单，可以切换查看不同分组的文档。这个功能我在做微服务网关时用过，非常实用。

API测试工具：不止是看文档

文档生成只是第一步。真正的好工具，得能直接在文档页面上调试接口。Swagger UI自带「Try it out」按钮，点一下就能填参数、发请求、看响应。

但我个人更推荐搭配使用 Postman 或 Insomnia。为什么？因为Swagger UI的测试功能比较基础，不支持环境变量、脚本、批量测试这些高级特性。

做法很简单：从Swagger UI页面导出OpenAPI JSON文件，然后导入到Postman中。Postman会自动生成所有接口的集合，你只需要填上Base URL就能开始测试。

我的习惯：开发阶段用Swagger UI快速验证，集成测试阶段用Postman跑自动化测试脚本。两者互补，效率很高。

避坑指南

我曾经踩过的坑：

Kotlin的默认参数值不会自动显示在文档中。需要手动用 @Schema(defaultValue = "...") 标注。
如果Controller参数用了 @RequestParam 且是必填的，记得加 required = true，否则文档里会显示为可选。
SpringDoc默认不扫描 @RestControllerAdvice 中的异常处理。需要额外配置才能让全局异常响应出现在文档里。

知识体系一览

下面这张图梳理了本章的核心逻辑，从规范到工具再到测试，一条线串起来：

总结一下

API文档这件事，说白了就是「写一次，到处用」。你花半小时把注解加好，后面前端、测试、甚至运维都能直接受益。我个人觉得，这是投入产出比非常高的一件事。

如果你刚开始接触，建议先从SpringDoc集成入手，跑通Swagger UI页面。然后逐步给关键接口加上 @Operation 和 @Schema 注解。等熟练了，再研究分组、多版本、以及和Postman的联动。

嗯，今天就聊到这儿。记住一点：好的API文档，不是写出来的，是「生」出来的——让工具帮你生成，你只负责补充业务描述就够了。

📚 课程目录