mintlify__docs/zh/guides/developer-documentation.mdx

---
title: "创建开发者文档"
sidebarTitle: "开发者文档"
description: "构建帮助工程师集成你的 API、SDK 和工具的开发者文档，包括快速入门、参考文档和使用指南。"
keywords: ["开发者文档", "API 文档", "SDK 文档", "技术文档", "开发者门户"]
---

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

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

* **API 参考生成**：从 OpenAPI 规范生成交互式 [API 参考](/zh/api-playground/overview)，让开发者可以在你的文档中测试接口。
* **带说明的代码块**：[AI 助手](/zh/assistant/index) 会结合上下文解释代码示例，帮助开发者理解实现细节。
* **Git 同步**：使用 [GitHub](/zh/deploy/github)、[GitLab](/zh/deploy/gitlab) 或 [Bitbucket Cloud](/zh/deploy/bitbucket) 让文档与你的代码库保持同步。
* **版本管理**：维护多个[版本](/zh/organize/navigation#versions)的文档，让使用旧版本的开发者也能找到准确的信息。

<div id="prerequisites">
  ## 前提条件
</div>

如果尚未创建 Mintlify 项目，请参阅[快速开始](/zh/quickstart)以部署你的文档站点。

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

<div id="migrate-existing-documentation">
  ## 迁移现有文档
</div>

如果你是从头开始编写文档，请跳到[规划文档结构](#plan-your-documentation-structure)。

<div id="audit-existing-content">
  ### 审核现有内容
</div>

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

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

<div id="export-your-existing-content">
  ### 导出现有内容
</div>

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

<div id="plan-your-documentation-structure">
  ## 规划你的文档结构
</div>

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

```json 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"
        ]
      }
    ]
  }
}
```

如需了解更多配置选项，请参阅 [导航](/zh/organize/navigation)。

<div id="set-up-your-api-reference">
  ## 设置 API 参考文档
</div>

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

<Steps>
  <Step title="添加你的 OpenAPI 规范">
    将你的 OpenAPI 规范文件添加到项目中。你可以使用 YAML 或 JSON 格式。

    ```text
    your-project/
    ├── docs.json
    ├── openapi.yaml
    └── api-reference/
        └── overview.mdx
    ```
  </Step>

  <Step title="在 docs.json 中配置规范">
    在你的 `docs.json` 配置中引用你的 OpenAPI 规范文件。

    ```json 配置示例
    {
      "openapi": "openapi.yaml"
    }
    ```
  </Step>

  <Step title="将端点添加到导航中">
    将这些端点添加到 `docs.json` 的导航中。配置选项参见 [OpenAPI 设置](/zh/api-playground/openapi-setup)。

    ```json 导航示例
    {
      "group": "API 参考",
      "pages": [
        "api-reference/overview",
        "api-reference/users/list-users",
        "api-reference/users/get-user",
        "api-reference/users/create-user"
      ]
    }
    ```
  </Step>
</Steps>

<div id="set-up-the-assistant">
  ## 设置 AI 助手
</div>

AI 助手可以帮助开发者找到答案并理解代码示例。你可以在 [控制台](https://dashboard.mintlify.com/products/assistant/settings) 中进行配置。

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

<div id="set-up-versioning">
  ## 设置版本管理
</div>

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

```json 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"]
      }
    ]
  }
}
```

如需了解更多信息，请参阅[版本](/zh/organize/navigation#versions)。

<div id="connect-to-your-repository">
  ## 连接到你的存储库
</div>

安装 Mintlify [GitHub 应用](/zh/deploy/github)，使文档与你的代码库保持同步，并支持协作贡献。

<Steps>
  <Step title="连接你的存储库">
    在[控制台](https://dashboard.mintlify.com)中链接你的 GitHub 存储库。在你推送更改时，这将启用自动部署。
  </Step>

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

<Note>
  如果你使用 GitLab，请查看 [GitLab](/zh/deploy/gitlab) 以获取配置说明。
</Note>

<div id="maintain-your-documentation">
  ## 维护文档
</div>

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

<Steps>
  <Step title="保持 API 参考文档最新">
    每次发布变更时都要更新 OpenAPI 规范。如果你从代码生成规范，请在发布流程中将这一步自动化。
  </Step>

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

  <Step title="维护更新日志">
    记录破坏性变更、新功能和弃用项。开发者依赖更新日志来了解各版本之间发生了哪些变化。更多信息请参阅 [更新日志](/zh/create/changelogs)。
  </Step>

  <Step title="监控反馈">
    查看 AI 助手会话和搜索分析数据，以识别文档中的不足。如果开发者反复询问同一主题，请改进相应部分。更多信息请参阅 [维护](/zh/guides/maintenance)。
  </Step>
</Steps>

<div id="next-steps">
  ## 后续步骤
</div>

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

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