创建开发者文档

构建帮助工程师集成你的 API、SDK 和工具的开发者文档，包括快速入门、参考文档和使用指南。

开发者文档帮助人们了解并集成你的产品。优秀的文档能让用户更充分地使用你的产品，减少支持成本，加快产品采用速度，并提升开发者体验。

Mintlify 提供专为开发者文档打造的基础设施。

• API 参考生成：从 OpenAPI 规范生成交互式 API 参考，让开发者可以在你的文档中测试接口。
• 带说明的代码块：AI 助手 会结合上下文解释代码示例，帮助开发者理解实现细节。
• Git 同步：使用 GitHub 或 GitLab 让文档与你的代码库保持同步。
• 版本管理：维护多个版本的文档，让使用旧版本的开发者也能找到准确的信息。

​

前提条件

如果尚未创建 Mintlify 项目，请参阅快速开始以部署你的文档站点。

• 以 OpenAPI 格式编写的 API 规范 (如果你要为 API 编写文档)
• 存放文档的 Git 存储库
• 在你的 Mintlify 组织中的管理员权限

​

迁移现有文档

如果你是从头开始编写文档，请跳到规划文档结构。

​

审核现有内容

检查你当前的文档，以明确已经有哪些内容，以及哪些需要迁移。

• API reference：它是由规范自动生成的还是手写的？你为哪些端点编写了文档？
• Guides and tutorials：有哪些集成指南？它们是否是最新的？
• Code examples：你使用了哪些编程语言和框架？
• SDK documentation：你是否为每个 SDK 提供了单独的文档？
• Changelog：你是否维护更新日志或版本发布说明？
• Metadata：你的内容是否包含诸如日期、作者和标签等 metadata？

​

导出现有内容

• 导出为 Markdown，以最简便的方式迁移到 Mintlify。
• 导出 OpenAPI 规范，以便用于 API 参考文档。
• 如果无法导出为 Markdown，可先导出为 HTML，然后再转换为 Markdown。

​

规划你的文档结构

开发文档通常包含多种内容类型。请围绕用户理解你产品的方式来设计导航结构。

docs.json example

{
  "navigation": {
    "groups": [
      {
        "group": "Get Started",
        "pages": [
          "introduction",
          "quickstart",
          "authentication"
        ]
      },
      {
        "group": "Guides",
        "pages": [
          "guides/webhooks",
          "guides/error-handling",
          "guides/rate-limits",
          "guides/pagination"
        ]
      },
      {
        "group": "API 参考",
        "pages": [
          "api-reference/overview",
          "api-reference/users",
          "api-reference/orders",
          "api-reference/products"
        ]
      },
      {
        "group": "SDKs",
        "pages": [
          "sdks/javascript",
          "sdks/python",
          "sdks/go"
        ]
      }
    ]
  }
}

如需了解更多配置选项，请参阅 导航。

​

设置 API 参考文档

如果你有 API，可以根据 OpenAPI 规范生成交互式参考文档。

1. 添加你的 OpenAPI 规范

   将你的 OpenAPI 规范文件添加到项目中。你可以使用 YAML 或 JSON 格式。

   your-project/
   ├── docs.json
   ├── openapi.yaml
   └── api-reference/
       └── overview.mdx
   
2. 在 docs.json 中配置规范

   在你的 docs.json 配置中引用你的 OpenAPI 规范文件。

   配置示例

   {
     "openapi": "openapi.yaml"
   }
   
3. 将端点添加到导航中

   将这些端点添加到 docs.json 的导航中。配置选项参见 OpenAPI 设置。

   导航示例

   {
     "group": "API 参考",
     "pages": [
       "api-reference/overview",
       "api-reference/users/list-users",
       "api-reference/users/get-user",
       "api-reference/users/create-user"
     ]
   }
   

​

设置 AI 助手

AI 助手可以帮助开发者找到答案并理解代码示例。你可以在 控制台 中进行配置。

• 示例问题：添加面向开发者的问题，例如“如何为 API 请求进行身份验证？”或“给我展示如何处理 webhooks。”
• 代码讲解：当开发者就特定示例提问时，AI 助手可以结合上下文对代码块进行讲解。

​

设置版本管理

如果你维护多个 API 版本，请配置版本管理，便于开发者查阅对应版本的文档。

Versioning example

{
  "versions": ["v2", "v1"],
  "navigation": {
    "groups": [
      {
        "group": "API 参考",
        "version": "v2",
        "pages": ["v2/api-reference/users"]
      },
      {
        "group": "API 参考",
        "version": "v1",
        "pages": ["v1/api-reference/users"]
      }
    ]
  }
}

如需了解更多信息，请参阅版本。

​

连接到你的存储库

安装 Mintlify GitHub 应用，使文档与你的代码库保持同步，并支持协作贡献。

1. 连接你的存储库

   在控制台中链接你的 GitHub 存储库。在你推送更改时，这将启用自动部署。

2. 配置 branch 设置

   设置你的生产 branch，并为拉取请求 (PR；亦称“合并请求”/Merge Request) 启用预览部署。这样你就可以在文档上线之前审查这些更改。

如果你使用 GitLab，请查看 GitLab 以获取配置说明。

​

维护文档

开发者文档需要定期更新，以确保信息准确且易用。

1. 保持 API 参考文档最新

   每次发布变更时都要更新 OpenAPI 规范。如果规范是从代码生成的，请在发布流程中将这一步自动化。

2. 更新代码示例

   在发布新的 SDK 版本或产品更新时，审查代码示例。过时的示例会导致集成失败并增加支持请求。

3. 维护更新日志

   记录破坏性变更、新功能和弃用项。开发者依赖更新日志来了解各版本之间发生了哪些变化。更多信息请参阅 更新日志。

4. 监控反馈

   查看 AI 助手会话和搜索分析数据，以识别文档中的不足。如果开发者反复询问同一主题，请改进相应部分。更多信息请参阅 维护。

​

后续步骤

你的开发者文档已经准备好上线。在完成部署后：

1. 向你的开发者社区发布文档上线公告。
2. 监控搜索行为和 AI 助手对话，发现文档中的空白。
3. 制定流程，在每次 API 发布时更新文档。
4. 收集开发者反馈，持续改进文档内容。