API 文档生成

Unicode Framework 提供了自动生成 API 文档的功能，可以根据路由定义自动生成完整的 API 文档。

生成文档

使用命令行

<h1 id="基本用法">基本用法</h1>
php console api:doc <app-name>
<h1 id="指定输出文件">指定输出文件</h1>
php console api:doc index --output docs/api.json
<h1 id="指定标题和版本">指定标题和版本</h1>
php console api:doc index --output docs/api.json --title "API Documentation" --version "1.0.0"
<h1 id="指定描述和基础-url">指定描述和基础 URL</h1>
php console api:doc index --output docs/api.json --description "API Documentation" --base-url "https://api.example.com"

选项说明

• --output, -o: 输出文件路径（JSON 格式）
• --title: 文档标题
• --version: API 版本号
• --description: 文档描述
• --base-url, --base_url: API 基础 URL

文档格式

JSON 格式

生成的文档是 JSON 格式，包含以下结构：

{
  "info": {
    "title": "API Documentation",
    "version": "1.0.0",
    "description": "API Documentation",
    "base_url": "https://api.example.com"
  },
  "routes": [
    {
      "method": "GET",
      "path": "/api/users",
      "name": "api.users.index",
      "handler": "App\\Index\\Controller\\UserController@index",
      "parameters": [],
      "middleware": []
    }
  ]
}

文档内容

路由信息

文档包含以下路由信息：

• method: HTTP 方法（GET, POST, PUT, DELETE 等）
• path: 路由路径
• name: 路由名称
• handler: 处理器（控制器方法或闭包）
• parameters: 路由参数
• middleware: 中间件列表

示例文档

{
  "info": {
    "title": "User API",
    "version": "1.0.0",
    "description": "User management API",
    "base_url": "https://api.example.com"
  },
  "routes": [
    {
      "method": "GET",
      "path": "/api/users",
      "name": "api.users.index",
      "handler": "App\\Index\\Controller\\UserController@index",
      "parameters": [],
      "middleware": ["jwt"]
    },
    {
      "method": "GET",
      "path": "/api/users/{id}",
      "name": "api.users.show",
      "handler": "App\\Index\\Controller\\UserController@show",
      "parameters": [
        {
          "name": "id",
          "type": "integer",
          "required": true
        }
      ],
      "middleware": ["jwt"]
    },
    {
      "method": "POST",
      "path": "/api/users",
      "name": "api.users.store",
      "handler": "App\\Index\\Controller\\UserController@store",
      "parameters": [],
      "middleware": ["jwt"]
    }
  ]
}

自定义文档

使用 API 文档生成器

use Unicode\Framework\Documentation\ApiDocGenerator;
use Unicode\Framework\Config\Config;
use Unicode\Framework\Route\Router;
$config = Config::getInstance();
$router = new Router();
$generator = new ApiDocGenerator($config, $router);
$doc = $generator->generate('index', [
    'title' => 'My API',
    'version' => '1.0.0',
    'description' => 'API Description',
    'base_url' => 'https://api.example.com',
]);
// 保存文档
file_put_contents('docs/api.json', json_encode($doc, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE));

过滤路由

$doc = $generator->generate('index', [
    'title' => 'Public API',
    'filter' => function($route) {
        // 只包含公开路由
        return !in_array('jwt', $route->middleware);
    },
]);

最佳实践

1. 文档组织

<h1 id="推荐按应用组织文档">✅ 推荐：按应用组织文档</h1>
php console api:doc index --output docs/api-index.json
php console api:doc admin --output docs/api-admin.json
php console api:doc api --output docs/api-api.json

2. 版本管理

<h1 id="推荐在文档中包含版本信息">✅ 推荐：在文档中包含版本信息</h1>
php console api:doc index --output docs/api-v1.json --version "1.0.0"
php console api:doc index --output docs/api-v2.json --version "2.0.0"

3. 自动化生成

<h1 id="推荐在-cicd-中自动生成文档">✅ 推荐：在 CI/CD 中自动生成文档</h1>
<h1 id="githubworkflowsdocsyml">.github/workflows/docs.yml</h1>
name: Generate API Docs
on:
  push:
    branches: [main]
jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate API Docs
        run: |
          php console api:doc index --output docs/api.json
          git add docs/api.json
          git commit -m "Update API docs"
          git push

4. 文档更新

<h1 id="推荐定期更新文档">✅ 推荐：定期更新文档</h1>
<h1 id="在部署脚本中">在部署脚本中</h1>
php console api:doc index --output docs/api.json

5. 文档格式

<h1 id="推荐使用格式化的-json">✅ 推荐：使用格式化的 JSON</h1>
php console api:doc index --output docs/api.json
<h1 id="格式化-json使用-jq">格式化 JSON（使用 jq）</h1>
cat docs/api.json | jq '.' > docs/api-formatted.json

常见问题

Q: 如何生成多个应用的文档？

A: 分别为每个应用生成文档：

php console api:doc index --output docs/api-index.json
php console api:doc admin --output docs/api-admin.json

Q: 文档包含哪些信息？

A: 包含路由方法、路径、名称、处理器、参数和中间件信息。

Q: 如何自定义文档格式？

A: 使用 ApiDocGenerator 类，自定义生成逻辑。

Q: 文档可以导出为其他格式吗？

A: 目前支持 JSON 格式，可以编写脚本转换为其他格式（如 Markdown、HTML）。

Q: 如何过滤路由？

A: 在生成文档时使用过滤器函数。

相关文档

• 路由系统 - 路由定义
• 命令行工具 - 命令使用
• 多应用架构 - 多应用文档生成