Skip to main content
开发者文档帮助人们了解并集成你的产品。优秀的文档能让用户更充分地使用你的产品，减少支持成本，加快产品采用速度，并提升开发者体验。 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. 收集开发者反馈，持续改进文档内容。