跳转到正文
API 101
本文目录

第 92 篇

API 文档生成工具怎么选?

要点速览

  • 先确定权威来源,再选渲染工具。 代码注解、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 客户端,也可以从请求集合生成文档。

流程:

  1. 在 Postman 集合中创建 API 请求。
  2. 添加说明、保存请求和响应示例,并补充测试。
  3. 从集合生成并发布文档。
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 /docs

FastAPI 利用 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 --parseInternal

Java: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-docs
1// 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 文档改善开发者体验,了解如何让生成的参考文档支持安全、明确的开发任务。

编辑本篇文章

获取方案