第 92 篇
API 文档生成工具怎么选?
API7.ai
2026年05月21日
要点速览
- 先确定权威来源,再选渲染工具。 代码注解、OpenAPI 描述、请求集合和运行时发现对应不同的维护与治理方式。
- 生成的是参考文档。 教程、概念说明、迁移指南和故障排查仍需要人工编写。
- 界面好用只是一个条件。 验证、审阅、版本管理、部署、访问控制和导出能力决定工具是否适合长期使用。
- 用实际实现验证生成结果。 自动化可以生成正确的文档,也会照样复制过时的说明和有误的示例。
- 优先选择可移植的契约。 遵循标准的源文件可以减少对特定编辑器、渲染工具或托管平台的依赖。
手工编写和维护 API 文档费时且容易出错。API 一旦演进,文档便可能跟不上实现。自动生成可以从代码、规范或运行时行为提取参考资料,降低维护负担。本文介绍常用工具的优缺点,以及如何按技术栈和工作流选择。
| 主要需求 | 权威来源 | 常用工具 | 适用场景 | 主要风险 |
|---|---|---|---|---|
| 交互式参考文档 | OpenAPI 描述 | Swagger UI、Redoc、Stoplight | 设计优先或契约优先的 API | 契约内容少,生成的文档也会很简略 |
| 基于集合发布 | 已保存的请求和示例 | Postman | 已在管理请求集合的团队 | 部分下游工具无法直接使用集合 |
| 框架原生参考文档 | 路由、类型和注解 | FastAPI、SpringDoc、swagger-jsdoc、swaggo/swag | 代码优先的服务 | 注解可能表达不了全部运行时行为 |
| 指南与参考文档同站发布 | Markdown 和 API 契约 | Docusaurus、MkDocs、OpenAPI 插件 | 既需要教程,也需要参考文档的产品 | 团队需承担更多构建和部署工作 |
| 发现遗留 API | 观测流量或已部署路由 | 运行时发现和网关导出 | 建立第一份 API 清单 | 可能采集到敏感信息或未公开行为 |
本文聚焦文档生成和工具选择。关于 API 的设计、实现、测试、安全和运维,参见如何构建你的第一个 API。
为什么要自动生成文档?
手工维护文档经常遇到以下问题:
文档滞后。 代码在一个 PR 里变了,文档却要等另一个 PR,甚至始终没人更新。久而久之,开发者不再信任文档。
覆盖不全。 新增端点、参数或错误码时容易漏写,遗漏又不一定立刻能发现。
格式不一致。 每个人的写法不同,端点说明的结构和详略程度也不统一。
维护成本高。 一份详尽的端点文档可能要写几个小时,赶进度时很容易被搁置。
自动生成把代码或规范作为权威来源。来源变更后,参考文档可以随之更新,结构更一致,缺项也更容易发现。内容是否完整准确,仍需对照实际行为验证并经过人工审阅。
生成 API 文档的三种方法
1. 从代码注解生成
工具解析源码里的注解和注释。开发者通过特定格式的注释或装饰器描述端点、参数和响应。
优点:
- 文档与代码保存在同一个文件
- 可以随代码一起审阅
- 可利用类型系统自动生成参数说明
- 适合不维护独立规范的团队
局限:
- 需要持续补齐注解
- 输出质量取决于开发者写得是否充分
- 大量注解可能影响代码阅读
- 生成结果往往缺少面向任务的指南和教程
适合: 代码优先的团队、使用强类型语言的服务、内部 API。
2. 从 API 规范生成
工具从 OpenAPI、RAML 或 API Blueprint 等规范生成文档,以规范文件作为正式契约。
优点:
- API 契约有统一的权威来源
- 同一份规范还能用于契约测试、模拟服务和客户端生成
- 支持先定义规范、再实现的设计优先流程
- 容易保持不同端点的文档结构一致
局限:
- 需要独立维护规范文件
- 缺少验证时,规范与实现仍会脱节
- 复杂规范有一定学习成本
- 可能需要额外工具来保持同步
适合: 公共 API、设计优先的团队、提供多种客户端 SDK 或需要契约测试的 API。
3. 从运行时观测生成
工具观察运行中的 API,发现端点、参数和响应结构。输入是观察到的实际行为,无需读取代码或规范。
优点:
- 不需要手工注解
- 能发现实际出现的行为
- 不受语言或框架限制
- 容易用于遗留 API
局限:
- 只能发现可观测的行为,可能遗漏错误分支或条件逻辑
- 需要运行中的 API 及获准的观测入口
- 无法自动推断设计意图、业务背景和完整说明
- 测试覆盖不足时,发现结果也会不完整
适合: 遗留 API、文档原型、尚无现成规范的 API。
1flowchart TD
2 A{"Existing source of truth?"}
3 A -- "Reviewed API contract" --> S["Specification-based generation"]
4 A -- "Framework routes and types" --> C["Code annotation generation"]
5 A -- "Only a running legacy API" --> R["Runtime discovery as a starting point"]
6 S --> V["Validate contract and examples"]
7 C --> V
8 R --> H["Human review and contract creation"]
9 H --> V
10 V --> P["Render reference plus authored guides"]
11
12 classDef source fill:#e8f3ff,stroke:#1677ff,color:#102a43;
13 classDef check fill:#fff7e6,stroke:#d48806,color:#5c3b00;
14 classDef done fill:#f6ffed,stroke:#389e0d,color:#173b0b;
15 class S,C,R source;
16 class V,H check;
17 class P done;常用 API 文档生成工具
Swagger 和 OpenAPI 工具
OpenAPI 规范是一种广泛使用的 HTTP API 描述标准。多种工具可以用 OpenAPI 描述生成参考文档。
Swagger UI 可以直接渲染 OpenAPI 描述,提供可交互的参考页面:
1# openapi.yaml
2openapi: 3.1.0
3info:
4 title: User Management API
5 version: 1.0.0
6 description: Secure user authentication and profile management
7
8paths:
9 /users:
10 post:
11 summary: Create new user
12 requestBody:
13 required: true
14 content:
15 application/json:
16 schema:
17 type: object
18 required: [email, name]
19 properties:
20 email:
21 type: string
22 format: email
23 examples: [user@example.com]
24 name:
25 type: string
26 minLength: 2
27 maxLength: 100
28 responses:
29 '201':
30 description: User created successfully
31 content:
32 application/json:
33 schema:
34 $ref: '#/components/schemas/User'
35components:
36 schemas:
37 User:
38 type: object
39 required: [id, email, name]
40 properties:
41 id:
42 type: string
43 examples: [usr_123]
44 email:
45 type: string
46 format: email
47 name:
48 type: string启动文档预览: 在含有 openapi.yaml 的项目目录运行。Redocly 命令需要事先安装并固定 @redocly/cli。
1# Using Swagger UI (Docker)
2docker run -p 8080:8080 \
3 -e SWAGGER_JSON=/api/openapi.yaml \
4 -v $(pwd):/api \
5 swaggerapi/swagger-ui
6
7# Using Redoc (alternative renderer)
8mkdir -p docs
9npx --no-install redocly build-docs openapi.yaml \
10 --output docs/index.html
优点: 标准通用,工具丰富,支持在线试用,生态中也有规范验证工具。
局限: 复杂 API 的 YAML 文件容易变长,需要持续维护规范,且不擅长承载长篇指南。
Postman
Postman 主要是 API 客户端,也可以从请求集合生成文档。
流程:
- 在 Postman 集合中创建 API 请求。
- 添加说明、保存请求和响应示例,并补充测试。
- 从集合生成并发布文档。
1// Example Postman test that enhances documentation
2pm.test("User creation returns 201", function () {
3 pm.response.to.have.status(201);
4 pm.response.to.have.jsonBody("id");
5});
6
7// Check the response; save the example separately.
8pm.expect(pm.response.json()).to.have.property("email");上面的断言用于验证响应。需要展示该响应时,还要将请求和响应保存为示例。
优点: 已使用 Postman 的团队容易上手,可以保留真实请求与响应示例,支持发布和版本管理。
局限: 一些下游工具更容易处理 OpenAPI,且高级协作或治理能力取决于所用套餐。
Stoplight
Stoplight 提供 API 设计和文档平台,内置 OpenAPI 可视化编辑器。
主要功能:
- 用可视化界面编辑 OpenAPI,无需手写 YAML
- 自动生成文档并自定义主题
- 通过模拟服务在实现前测试
- 支持 API 治理和风格指南
新项目需要先在 openapi.yaml 所在目录创建 .spectral.yaml,启用 OpenAPI 规则。如果团队已有规则集,改用该文件的路径。从这个目录运行校验命令。
1# .spectral.yaml
2extends: ["spectral:oas"]1# Spectral CLI from Stoplight for CI validation
2npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml
优点: 适合设计优先的流程,支持可视化编辑、文档渲染和治理。
局限: 属于商业平台,完整功能依赖 Stoplight。
语言和框架专用工具
不同语言都有适配自身类型系统和编码习惯的工具。
Python:FastAPI
1# FastAPI automatically generates OpenAPI specs
2from fastapi import FastAPI
3from pydantic import BaseModel, EmailStr
4
5app = FastAPI(title="User API", version="1.0.0")
6
7class UserCreate(BaseModel):
8 """User creation request model."""
9 email: EmailStr
10 name: str
11
12class User(BaseModel):
13 """User response model."""
14 id: str
15 email: EmailStr
16 name: str
17 created_at: str
18
19@app.post("/users", response_model=User, status_code=201)
20async def create_user(user: UserCreate):
21 """
22 Create a new user account.
23
24 Args:
25 user: User creation data including email and name
26
27 Returns:
28 Created user object with generated ID
29
30 This compact example returns synthetic data so the generated try-it
31 operation remains executable. Replace it with persistence in a real API.
32 """
33 return User(
34 id="usr_123",
35 email=user.email,
36 name=user.name,
37 created_at="2026-07-21T00:00:00Z",
38 )
39
40# OpenAPI docs automatically available at /docsFastAPI 利用 Python 类型提示和文档字符串生成 OpenAPI 描述与 Swagger UI。运行包含 EmailStr 的示例时,需要安装 email-validator,并使用 Uvicorn 等 ASGI 服务器启动应用。
Node.js:JSDoc + swagger-jsdoc
1/**
2 * @swagger
3 * /users:
4 * post:
5 * summary: Create new user
6 * requestBody:
7 * required: true
8 * content:
9 * application/json:
10 * schema:
11 * type: object
12 * required:
13 * - email
14 * - name
15 * properties:
16 * email:
17 * type: string
18 * format: email
19 * name:
20 * type: string
21 * responses:
22 * 201:
23 * description: User created successfully
24 */
25app.post('/users', async (req, res) => {
26 // Implementation
27});
28
29// Generate OpenAPI spec from JSDoc comments
30const swaggerSpec = swaggerJsdoc({
31 definition: {
32 openapi: '3.0.0',
33 info: { title: 'User API', version: '1.0.0' }
34 },
35 apis: ['./routes/*.js']
36});Go:swaggo/swag
1// @Summary Create user
2// @Description Create a new user account with email and name
3// @Tags users
4// @Accept json
5// @Produce json
6// @Param user body UserCreate true "User creation data"
7// @Success 201 {object} User
8// @Failure 400 {object} ErrorResponse
9// @Failure 409 {object} ErrorResponse
10// @Router /users [post]
11func CreateUser(c *gin.Context) {
12 // Implementation
13}
14
15// Generate docs with:
16// swag init --parseDependency --parseInternalJava:SpringDoc(Spring Boot)
1@RestController
2@RequestMapping("/users")
3@Tag(name = "User Management", description = "User creation and profile management")
4public class UserController {
5
6 @PostMapping
7 @Operation(
8 summary = "Create new user",
9 description = "Creates a user account with provided email and name"
10 )
11 @ApiResponses({
12 @ApiResponse(responseCode = "201", description = "User created successfully"),
13 @ApiResponse(responseCode = "400", description = "Invalid input"),
14 @ApiResponse(responseCode = "409", description = "Email already exists")
15 })
16 public ResponseEntity<User> createUser(
17 @Valid @RequestBody UserCreateRequest request
18 ) {
19 // Implementation
20 }
21}
22
23// OpenAPI spec automatically generated at /v3/api-docs
24// Swagger UI automatically available at /swagger-ui.html文档即代码工具
Meta 的 Docusaurus 和 MkDocs 都可以用 Markdown 文件建立文档即代码工作流:
1# Docusaurus setup
2npx create-docusaurus@latest api-docs classic
3cd api-docs
4
5# Add OpenAPI plugin
6npm install docusaurus-plugin-openapi-docs
7npm install docusaurus-theme-openapi-docs1// Configure in docusaurus.config.js
2export default {
3 presets: [
4 [
5 'classic',
6 {
7 docs: {
8 docItemComponent: '@theme/ApiItem',
9 },
10 },
11 ],
12 ],
13 plugins: [
14 [
15 'docusaurus-plugin-openapi-docs',
16 {
17 id: 'api',
18 docsPluginId: 'classic',
19 config: {
20 userApi: {
21 specPath: 'openapi.yaml',
22 outputDir: 'docs/api',
23 },
24 },
25 },
26 ],
27 ],
28 themes: ['docusaurus-theme-openapi-docs'],
29};以上是 Docusaurus OpenAPI 插件的配置片段。请选用与 Docusaurus 版本兼容的插件和主题,并在构建前执行插件提供的 gen-api-docs 命令生成参考页。
优点: 能控制站点呈现,把 API 参考与指南、教程放在一起。源文件便于版本管理,静态站点也易于部署。
局限: 相较托管方案,初始设置更多,部署基础设施也由团队维护。
API 网关能提供哪些文档素材?
Apache APISIX 等 API 网关可以导出路由配置作为参考素材。APISIX 本身不会直接生成文档,但可以:
- 用第三方工具把路由配置转换为 OpenAPI 格式
- 记录限流、认证策略、路由规则等网关层行为
- 将 APISIX Admin API 的响应接入文档生成流水线
1# Example: Fetch APISIX routes via Admin API
2set -o pipefail
3curl --fail-with-body http://127.0.0.1:9180/apisix/admin/routes \
4 -H "X-API-KEY: $APISIX_ADMIN_KEY" | \
5 jq '.list[]?.value | {uri, methods, configured_route_plugin_names: ((.plugins // {}) | keys)}'
6
7# Review the allowlisted output before using it as documentation input这有助于比对文档与已部署的网关路由。导出的插件名只表示路由上配置过的插件,无法判定它们是否启用、是否由其他配置层级继承,或是否真的执行。生成清单时还要考虑分页和所用 APISIX 版本的响应结构。Admin API 只应从获准的管理环境访问。原始插件配置可能含凭据、上游请求头或其他敏感值;只导出确认可公开的字段,筛除内部路由及敏感信息,再经人工审核后使用。
如何选择合适的工具?
以下情况适合代码注解:
- 团队采用代码优先流程
- 使用类型推断能力较强的强类型语言
- 希望在 PR 中同时审阅代码和文档
- API 主要供内部使用
以下情况适合从规范生成:
- API 采用设计优先流程
- 需要契约测试和客户端生成
- 面向公众提供 API 并有 SLA 承诺
- 多个团队接入同一个 API
以下情况适合运行时观测:
- 需要给没有规范的存量 API 补文档
- 需要快速制作文档原型
- API 框架对注解的支持有限
- 想检查文档是否与实际行为一致
以下情况适合文档即代码平台:
- API 参考文档需要搭配使用指南
- 希望控制文档站点的设计
- 文档需求较复杂
- 团队希望使用基于 Git 的工作流
生成文档的实践建议
1. 像管理代码一样管理规范。 将规范纳入版本控制,在 PR 中审阅,与代码一起管理版本。
2. 验证规范与实现一致。 可以用 Prism 对实际服务流量做规范验证,或使用 Pact 进行提供方验证。仅检查由规范生成的模拟响应,不能证明实现符合契约。
3. 在 CI 中生成文档。 让主分支变更触发构建并产出静态文件。下面展示生成步骤;项目应提供 generate:openapi 脚本,并在依赖锁文件中固定生成器版本。发布时,使用官方 GitHub Pages 工作流上传并部署生成的目录。
1# GitHub Actions example
2name: Generate API Docs
3
4on:
5 push:
6 branches: [main]
7
8permissions:
9 contents: read
10
11jobs:
12 docs:
13 runs-on: ubuntu-latest
14 steps:
15 - uses: actions/checkout@v6
16
17 - name: Install dependencies
18 run: npm ci
19
20 - name: Generate OpenAPI spec
21 run: npm run generate:openapi
22
23 - name: Build documentation
24 run: |
25 mkdir -p docs
26 npx --no-install redocly build-docs openapi.yaml --output docs/index.html
4. 补充人工内容。 在自动生成的结构化参考内容之外,加入:
- 概念概览和架构图
- 常见工作流的教程
- 故障排查指南和常见问题
- 版本升级的迁移指南
5. 观察文档使用情况。 关注访问最多的页面、开发者在哪里退出,以及他们在搜索什么,用这些线索安排改进顺序。
6. 测试文档示例。 在 CI 中提取并运行可执行示例,尽早发现损坏的代码。
1flowchart LR
2 S["Contract, annotations, or collection"] --> L["Parse and lint"]
3 L --> E["Validate examples"]
4 E --> C["Compare with implementation"]
5 C --> R["Render and preview"]
6 R --> H["Add guides and troubleshooting"]
7 H --> P["Publish immutable version"]
8 P --> M["Monitor use and freshness"]
9 M --> S
10
11 classDef check fill:#fff7e6,stroke:#d48806,color:#5c3b00;
12 classDef ready fill:#f6ffed,stroke:#389e0d,color:#173b0b;
13 class L,E,C,R check;
14 class H,P,M ready;小结
自动生成让参考文档的维护变成可重复、可审阅的流程。先选定权威来源,再匹配 OpenAPI 渲染器、框架原生工具、请求集合或综合文档平台,才能更容易让文档跟上实现。
从团队现有流程入手。已维护 OpenAPI 描述的团队可以试用 Swagger UI 或 Redoc;采用代码优先流程的团队可以先看框架支持的注解工具。选定方式后,在 CI 中自动生成,并随兼容的 API 变更一起发布文档。
生成可以让文档滞后更容易被发现,但正确性仍要靠契约验证、实现测试和人工审阅。接下来可阅读如何用交互式 API 文档改善开发者体验,了解如何让生成的参考文档支持安全、明确的开发任务。