跳到主要内容

API 文档自动生成工具调研报告

调研概述​

本文档整理了API文档自动生成的主流工具，涵盖OpenAPI/Swagger、GraphQL、代码注释生成文档等方案。这些工具能够从代码自动生成文档，保持文档与代码同步，大幅降低文档维护成本。

核心价值：

  • 自动生成API文档，减少手动维护
  • 代码与文档同步，避免文档过期
  • 提供交互式API测试
  • 降低API学习成本

📖 快速导航​

按类型分类​

  1. OpenAPI/Swagger 工具 - REST API 文档标准
  2. GraphQL 文档工具 - GraphQL API 文档
  3. 代码注释生成文档 - TypeScript/JavaScript/Python 等
  4. API Mock 工具 - API 模拟测试
  5. API 测试工具 - 接口测试

按使用场景选择​

  • REST API 文档 → Swagger UI / Redoc / Scalar
  • GraphQL API → GraphQL Playground / Apollo Studio
  • TypeScript 项目 → TypeDoc / API Extractor
  • Python 项目 → Sphinx / MkDocs
  • API Mock → Prism / MSW / WireMock
  • API 测试 → Postman / Insomnia / Bruno / Hoppscotch

一、OpenAPI/Swagger 工具生态​

OpenAPI 规范简介​

OpenAPI（前身 Swagger）是 REST API 的标准描述格式。

规范版本：

  • OpenAPI 3.1（2021，最新）
  • OpenAPI 3.0（2017，主流）
  • Swagger 2.0（2014，旧版）

1. Swagger UI ⭐⭐⭐⭐⭐​

核心特点​

  • OpenAPI 文档可视化
  • 交互式 API 测试
  • 自动生成客户端代码
  • 支持 OAuth2

快速开始​

# openapi.yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

集成方式：

<!-- CDN --\>
\<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css"/\>
\<div id="swagger-ui"\></div\>
\<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"\></script\>
<script\>
  SwaggerUIBundle({
    url: "openapi.yaml",
    dom_id: '#swagger-ui',
  })
</script\>

2. Redoc ⭐⭐⭐⭐⭐​

核心特点​

  • 美观的三栏布局
  • 响应式设计
  • SEO 友好
  • 性能优秀

特色​

  • 比 Swagger UI 更美观
  • 适合公开文档
  • 支持深度链接
  • 左侧导航 + 中间内容 + 右侧示例

快速开始​

\<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"\></script\>
\<redoc spec-url="openapi.yaml"\></redoc\>

3. Scalar ⭐⭐⭐⭐⭐​

核心特点​

  • 现代化 UI（2024-2025 新秀）
  • 交互式 API 客户端
  • 代码生成
  • 美观主题

特色​

  • 比 Redoc 更现代
  • 集成 API 测试客户端
  • 多种语言代码示例
  • 暗黑模式

4. Stoplight Elements ⭐⭐⭐⭐​

核心特点​

  • Web Components
  • 高度可定制
  • 模块化设计

OpenAPI 工具对比​

工具美观度交互性性能适用场景
Swagger UI⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐内部文档、测试
Redoc⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐公开API文档
Scalar⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐现代化项目
Stoplight⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐定制需求

5. 代码生成 OpenAPI 规范​

TypeScript - tsoa​

import { Controller, Get, Route } from 'tsoa';

@Route('users')
export class UserController extends Controller {
  @Get('{userId}')
  public async getUser(userId: number): Promise<User\> {
    return await userService.get(userId);
  }
}

// 自动生成 openapi.json

Python - FastAPI​

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str

@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int):
    return {"id": user_id, "name": "John"}

# 自动生成 OpenAPI 文档
# 访问 /docs 查看

Go - swag​

// @Summary Get user
// @Description Get user by ID
// @Tags users
// @Param id path int true "User ID"
// @Success 200 {object} User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    // ...
}

// 生成命令: swag init

二、GraphQL 文档工具​

1. GraphQL Playground ⭐⭐⭐⭐⭐​

核心特点​

  • 交互式 GraphQL IDE
  • 自动补全
  • 查询历史
  • Schema 浏览

集成示例​

import { ApolloServer } from '@apollo/server';

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

// Playground 自动可用

2. GraphiQL ⭐⭐⭐⭐⭐​

核心特点​

  • 官方 IDE
  • 实时错误提示
  • Schema 文档
  • 插件系统

3. Apollo Studio ⭐⭐⭐⭐⭐​

核心特点​

  • 云端 GraphQL 平台
  • Schema 管理
  • 性能监控
  • 团队协作

4. Altair GraphQL Client ⭐⭐⭐⭐​

核心特点​

  • 桌面应用 + 浏览器扩展
  • 跨平台
  • 美观 UI
  • 请求历史

三、代码注释生成文档​

1. TypeDoc ⭐⭐⭐⭐⭐​

核心特点​

  • TypeScript 项目文档生成
  • 从 TSDoc 注释生成
  • 支持多种输出格式

使用示例​

/**
 * Calculate the sum of two numbers
 * @param a - First number
 * @param b - Second number
 * @returns The sum of a and b
 * @example
 * ```ts
 * add(1, 2) // returns 3
 * ```
 */
export function add(a: number, b: number): number {
  return a + b;
}
# 生成文档
npx typedoc --out docs src

2. JSDoc ⭐⭐⭐⭐⭐​

核心特点​

  • JavaScript 标准文档注释
  • 广泛支持
  • 类型提示

3. API Extractor ⭐⭐⭐⭐​

核心特点​

  • Microsoft 开发
  • 生成 .d.ts
  • API 报告
  • API 文档

4. Sphinx ⭐⭐⭐⭐⭐​

核心特点​

  • Python 标准文档工具
  • reStructuredText
  • 多种主题
  • 扩展丰富

使用示例​

def add(a: int, b: int) -\> int:
    """
    Add two numbers.

    :param a: First number
    :param b: Second number
    :return: Sum of a and b
    :raises TypeError: If inputs are not integers

    Example:
        \>\>\> add(1, 2)
        3
    """
    return a + b

5. rustdoc ⭐⭐⭐⭐⭐​

核心特点​

  • Rust 官方文档工具
  • Markdown 支持
  • 示例代码测试
  • 搜索功能

四、API Mock 工具​

1. Prism ⭐⭐⭐⭐⭐​

核心特点​

  • 基于 OpenAPI 规范
  • 自动生成 Mock API
  • 请求验证
  • 动态响应

使用示例​

# 安装
npm install -g @stoplight/prism-cli

# 启动 Mock Server
prism mock openapi.yaml

# API 可用：http://localhost:4010

2. MSW (Mock Service Worker) ⭐⭐⭐⭐⭐​

核心特点​

  • Service Worker 拦截
  • 浏览器 + Node.js
  • 无需修改代码
  • TypeScript 支持

使用示例​

import { http, HttpResponse } from 'msw';
import { setupWorker } from 'msw/browser';

const worker = setupWorker(
  http.get('/api/users', () =\> {
    return HttpResponse.json([
      { id: 1, name: 'John' },
      { id: 2, name: 'Jane' },
    ]);
  })
);

worker.start();

3. WireMock ⭐⭐⭐⭐⭐​

核心特点​

  • Java 平台
  • HTTP Mock Server
  • 请求匹配
  • 响应模板

4. json-server ⭐⭐⭐⭐​

核心特点​

  • 零代码 REST API
  • 基于 JSON 文件
  • 快速原型

使用示例​

// db.json
{
  "users": [
    { "id": 1, "name": "John" }
  ]
}
npx json-server db.json
# API 可用：http://localhost:3000/users

五、API 测试工具​

1. Bruno ⭐⭐⭐⭐⭐​

核心特点​

  • 开源 Postman 替代
  • 本地文件存储（Git 友好）
  • 无需云账号
  • 跨平台

优势​

✅ 完全离线 ✅ Git 版本控制 ✅ 无隐私担忧 ✅ 免费开源

2. Hoppscotch ⭐⭐⭐⭐⭐​

核心特点​

  • Web 端 API 测试
  • 开源免费
  • PWA 支持
  • 实时协作

3. Postman ⭐⭐⭐⭐⭐​

核心特点​

  • 最流行 API 工具
  • 团队协作
  • 自动化测试
  • Mock Server

劣势​

  • 需要账号
  • 某些功能收费
  • 较重

4. Insomnia ⭐⭐⭐⭐​

核心特点​

  • Kong 旗下
  • GraphQL 支持好
  • 插件系统

5. HTTPie ⭐⭐⭐⭐⭐​

命令行 HTTP 客户端，详见 Mac终端命令行工具

六、工具选择建议​

按场景选择​

场景推荐工具理由
REST API 文档Redoc / Scalar美观、现代
REST API 测试Swagger UI交互式测试
GraphQL 文档GraphiQL / Playground官方标准
TypeScript 项目TypeDoc原生支持
Python 项目Sphinx生态成熟
API MockPrism / MSW基于规范
API 测试工具Bruno / Hoppscotch开源免费

完整工作流​

方案 1: TypeScript REST API

1. 代码 → tsoa → OpenAPI 规范
2. OpenAPI → Scalar → 文档网站
3. OpenAPI → Prism → Mock Server
4. Bruno → API 测试

方案 2: Python FastAPI

1. FastAPI → 自动生成 OpenAPI
2. /docs → Swagger UI（内置）
3. /redoc → Redoc（内置）
4. Hoppscotch → API 测试

方案 3: GraphQL

1. GraphQL Schema → 类型定义
2. Apollo Server → GraphQL Playground
3. Apollo Studio → 监控和协作
4. Altair → 桌面测试工具

七、最佳实践​

1. 文档即代码​

  • 使用代码注释生成文档
  • 文档与代码同步
  • Git 版本控制

2. OpenAPI 优先​

  • 先设计 API 规范
  • 再实现代码
  • 自动验证

3. 交互式文档​

  • 提供 API 测试功能
  • 示例请求/响应
  • 代码示例

4. 持续集成​

  • CI 自动生成文档
  • 文档更新检查
  • 自动发布

八、总结​

核心推荐​

REST API：

  • 文档：Scalar（现代）/ Redoc（美观）
  • 测试：Swagger UI（交互）
  • Mock：Prism（基于规范）
  • 客户端：Bruno（开源）/ Hoppscotch（Web）

GraphQL：

  • 文档：GraphQL Playground
  • 测试：Altair
  • 平台：Apollo Studio

代码生成文档：

  • TypeScript：TypeDoc
  • Python：Sphinx
  • Rust：rustdoc

最小化起步：

# TypeScript 项目
npm install -D tsoa typedoc
npx typedoc

# Python 项目
pip install fastapi
# 自动生成文档：/docs

最后更新时间：2025-11-08 调研范围：20+ API 文档工具 重点推荐：Scalar、Redoc、Prism、Bruno、TypeDoc