Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API 文档

本页介绍了在所有 Decentraland 服务中使用 OpenAPI 规范编写 API 文档的标准。

目标

我们的 API 文档方案确保：

  • 标准化 - 所有服务的一致 OpenAPI 规范

  • 自动化 - 通过 GitHub Actions 进行校验、打包和部署

  • 集中化 - 所有服务文档通过 GitBook 发布

  • 归属 - 文档与各自的服务仓库保持一致

  • 可访问性 - 便于贡献者使用、保持最新的 API 参考文档

仓库结构

每个服务仓库都必须包含一个 /docs 目录，结构如下：

/docs
  openapi.yaml        # 唯一事实来源（OpenAPI 3.1）
  openapi.json        # 在 CI 中自动生成，用于 Hugo/渲染器
  index.html          # 自动生成的独立文档（可选）

文件要求

openapi.yaml

  • 必须 作为规范源文件

  • 必须 使用 OpenAPI 3.1 规范

  • 可以 带有服务标识前缀（例如 worlds-openapi.yaml)

  • 可以 如果需要可拆分到 components/ 或 examples/ 目录中

openapi.json

  • 在 CI/CD 期间自动生成

  • 供 Hugo 和其他渲染器使用

  • 不要手动编辑

index.html

  • 自动生成的独立文档

  • 使用 Redocly 构建

  • 部署到 GitHub Pages

OpenAPI 标准

在编写 openapi.yaml时，请遵循以下约定以确保一致性和清晰性。

端点摘要

必须 应与实际端点路径保持一致：

Operation ID

必须 包含服务名称以确保全局唯一：

命名约定: {serviceName}_{operationDescription}

  • 使用 camelCase

  • 要描述性强但保持简洁

  • 在有帮助时包含 HTTP 方法上下文（例如 createUser, deleteParcel)

版本控制

必须 使用语义化版本控制（MAJOR.MINOR.PATCH）在 info.version:

版本递增规则:

  • MAJOR：破坏性变更（不兼容的 API 变更）

  • MINOR：新功能（向后兼容）

  • PATCH：错误修复（向后兼容）

标签与分组

必须 使用标签对相关端点分组：

在 GitBook 的导航中，操作会按标签分组。为了更好的组织方式，请将相关端点归入同一标签。

完整示例

本地开发

在本地预览文档

使用 Redocly CLI 预览你的 OpenAPI 文档：

添加到 package.json

添加一个构建脚本以便使用：

安装 Redocly CLI

验证 OpenAPI 规范

自动化设置

步骤 1：配置 GitBook 密钥

要将 API 规范发布到 GitBook，请将这些密钥添加到你的仓库中：

设置 → 密钥和变量 → Actions → 新建仓库密钥

密钥名称
描述
查找位置

GITBOOK_ORGANIZATION_ID

你的 GitBook 组织 ID

GitBook 设置 → Organization

GITBOOK_TOKEN

GitBook API 令牌

GitBook 设置 → API Tokens

必须配置这些密钥，自动化工作流才能发布到 GitBook。

步骤 2：添加 GitHub Actions 工作流

创建 .github/workflows/build-api-docs.yml 到你的仓库中：

参数:

  • api-spec-file：OpenAPI 规范文件路径（通常是 docs/openapi.yaml)

  • output-file：生成 HTML 文档的位置

  • output-directory：输出文件目录

  • api-spec-name：API 规范的唯一名称（用于 GitBook）

  • node-version：要使用的 Node.js 版本

此工作流将会:

  1. ✅ 验证 OpenAPI 规范

  2. ✅ 将规范打包成单个文件

  3. ✅ 使用 Redocly 构建静态 HTML 文档

  4. ✅ 自动部署到 GitHub Pages

  5. ✅ 将规范发布到 GitBook（如果已配置密钥）

步骤 3：启用 GitHub Pages

在你的仓库中配置 GitHub Pages：

  1. 转到 设置 → Pages

  2. 在 构建和部署:

    • 下，将 来源 设置为 GitHub Actions

  3. 确保存在一个名为 github-pages

  4. 保存设置

在第一次成功运行工作流后，你的文档将可在以下地址访问：

  • HTML 文档: https://decentraland.github.io/<repo>/index.html

  • OpenAPI 规范: https://decentraland.github.io/<repo>/openapi.yaml

  • 打包后的 JSON: https://decentraland.github.io/<repo>/openapi.json

只要仓库存在且已启用 GitHub Pages，这些 URL 就会一直有效。

添加到 GitBook

一旦你的 API 文档部署完成，就将其添加到集中式 GitBook 文档中。

手动添加（当前流程）

  1. 导航到 GitBook 空间

  2. 前往 API 参考 部分

  3. 点击 添加 API 参考

  4. 输入你的服务详情：

    • 名称：你的服务名称（例如“Social Service”）

    • OpenAPI URL: https://decentraland.github.io/{repo-name}/openapi.yaml

  5. 保存

GitBook 集成特性

GitBook 将自动：

  • 解析你的 OpenAPI 规范

  • 生成交互式 API 文档

  • 根据标签创建端点导航

  • 提供“Try it”功能

  • 在你更新规范时保持文档同步

完整设置流程

初始设置

Unexpected error with integration mermaid: Integration is not installed on this space

持续更新

Unexpected error with integration mermaid: Integration is not installed on this space

最佳实践

文档质量

  • 要有描述性：编写清晰的摘要和描述

  • 提供示例：包含请求/响应示例

  • 记录错误：描述所有可能的错误响应

  • 使用组件：通过 $ref 复用 schema 以避免重复

  • 添加描述：每个参数、属性和响应都应有描述

最佳实践示例

Schema 复用性

安全方案

验证与质量检查

提交前验证

添加预提交钩子或 CI 检查：

常见验证规则

  • 所有路径都有操作 ID

  • 所有操作都有标签

  • 所有参数都有描述

  • 所有响应都有文档说明

  • 提供示例

  • Schema 被正确引用

故障排查

工作流失败

问题：GitHub Actions 工作流失败

解决方案:

  • 检查工作流日志中的验证错误

  • 运行 redocly lint docs/openapi.yaml 在本地

  • 验证工作流配置中的文件路径

  • 确保密钥已正确配置

GitHub Pages 无法工作

问题：文档未出现在 GitHub Pages URL

解决方案:

  • 验证仓库设置中已启用 GitHub Pages

  • 检查工作流是否已成功完成

  • 等待几分钟让 GitHub Pages 更新

  • 验证 github-pages 环境存在

GitBook 未同步

问题：GitBook 未显示更新后的 API 文档

解决方案:

  • 验证 GitBook 密钥是否正确

  • 检查 OpenAPI URL 是否可访问

  • 在 GitBook 中手动触发刷新

  • 验证 OpenAPI 规范是否有效

从现有文档迁移

如果你已有现有 API 文档：

  1. 导出为 OpenAPI：将现有文档转换为 OpenAPI 3.1 格式

  2. 验证：使用 redocly lint 以确保符合规范

  3. 添加工作流：设置 GitHub Actions 自动化

  4. 测试：验证文档能正确构建和部署

  5. 更新链接：将旧文档链接指向新的 GitHub Pages URL

  6. 归档旧文档：在过渡期间保留旧文档供参考

下一步

相关标准

资源

上一页概述
下一页依赖管理

最后更新于