![如何从零开始构建API文档 [技术作者路线图]](https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/7f6c4ca5-30ca-42fd-a473-d6262774e149.png)
如何从零开始构建API文档 [技术作者路线图]
内容提要
本文为首次编写API文档的技术作者提供从零开始的完整指南。核心步骤包括：先了解API解决的问题及用户需求，制定文档计划；准备写作工具；撰写初稿；编辑校对；提交审核；将Postman集合转为OpenAPI规范；迁移至文档工具；持续更新。文章还强调优化文档以适配AI代理，如自包含页面、结构化标题、生成llms.txt等，确保开发者能高效集成。
延伸解读
先理解产品，再写文档
文章强调，写API文档前应先理解API解决的业务问题，而非仅关注端点。这意味着要思考目标用户、使用场景和独特价值。通过测试API、与工程师沟通，可以收集到用户可能遇到的问题，从而制定以用户旅程为导向的文档计划。这种从产品视角出发的方法，有助于文档更贴合实际使用，提升采用率。
文档结构应跟随用户旅程
文档规划的关键在于按用户使用顺序组织内容，而非按端点列表。文章建议先定义用户角色和目标，再列出用户可能的问题和前置条件，最后按用户旅程分类端点。例如，将支付相关端点归入“支付”部分，并按“发起支付-验证-查询状态”的顺序排列。这种结构能让用户快速找到所需信息，减少困惑。
为AI代理优化文档的必要性
文章指出，51%的开发者日常使用AI工具，因此文档需适配AI代理。具体方法包括：让每个页面自包含、记录所有边缘情况和错误、结构化标题、添加图片替代文本、直接给出答案、使用Markdown格式、生成llms.txt文件，并利用Mintlify agent score评估效果。这些措施能帮助AI准确引用文档，提升开发者体验。
持续更新与自动化
文档上线后仍需保持与产品同步。文章建议将文档仓库与代码仓库紧密关联，利用Mintlify或GitBook的自动化工作流，在工程师更改用户可见功能时自动生成文档草稿并开启拉取请求，由人工审核后合并。这能确保文档始终准确，避免因过时信息导致用户信任流失。
Q&A
如何从零开始构建API文档？
从零开始构建API文档的步骤包括：1. 设定基础，了解API解决的问题和用户需求，测试API，与工程师沟通，制定文档计划；2. 准备写作工具，如风格指南、写作工具、截图工具和文档工具；3. 撰写初稿；4. 编辑校对；5. 提交审核；6. 将Postman集合转换为OpenAPI规范；7. 迁移到文档工具；8. 持续更新以保持准确性。
在编写API文档之前，需要做哪些准备工作？
准备工作包括：1. 思考API解决的业务问题，明确目标用户和独特价值；2. 了解API，获取技术笔记、凭据等；3. 像用户一样测试API，记录问题和异常；4. 与工程师会面，提问并记录答案；5. 制定文档计划，包括定义用户、用户目标、常见问题、前置条件、端点分类和基于用户旅程的大纲。
如何制定API文档计划？
制定文档计划的方法：1. 定义用户角色和技术水平；2. 明确用户目标，如独立集成API；3. 列出用户可能提出的问题；4. 确定用户测试API前需要完成的事项，如注册、获取API密钥；5. 根据用例对端点进行分类；6. 基于用户旅程创建大纲，通常包括文档标签页（介绍、快速入门、KYB、功能）和API参考标签页（介绍、认证、错误、速率限制、分页、端点）。
API文档中API参考部分应该包含哪些内容？
API参考部分应包含：介绍（API概述、基础URL、环境、内容类型、HTTP响应）、认证（如何获取凭据和认证请求）、错误（具体错误信息、原因和解决方法）、速率限制（每个端点的限制和超出后的处理）、分页（如果适用）、端点（每个端点需包含HTTP方法、描述、请求头、参数、请求示例和响应示例）。
如何将Postman集合转换为OpenAPI规范？
将Postman集合转换为OpenAPI规范可以手动或使用工具。文章建议使用转换工具，并提供了资源链接。转换后，可以轻松迁移到任何支持OpenAPI的文档工具，如Mintlify、Fern或GitBook。
如何将文档迁移到Mintlify？
迁移到Mintlify的步骤：1. 创建Mintlify账户；2. 登录；3. 在设置中配置Git设置，添加GitHub组织和文档仓库；4. 安装GitHub App以自动部署；5. 设置自定义域名；6. 克隆文档仓库到本地；7. 安装Mintlify CLI（需要Node.js v20.17.0+）；8. 探索项目结构（docs.json、MDX文件、assets）；9. 编辑MDX文件并运行mintlify dev预览；10. 将内容复制到MDX文件；11. 推送更改，自动部署。
如何保持API文档的更新？
保持文档更新的方法：1. 将文档仓库与源代码仓库保持接近，以便及时捕获代码变更；2. 使用自动化工具（如Mintlify或GitBook）连接文档仓库和代码仓库，当工程师做出影响用户的更改时，自动生成文档更新并开启拉取请求，由人工审核后合并。
如何优化API文档以适应AI代理？
优化API文档以适应AI代理的方法：1. 使页面自包含，包含所有必要信息；2. 记录所有边缘情况和错误并提供解决方案；3. 正确结构化标题（H1、H2、H3）；4. 为所有图片添加替代文本；5. 先给出答案，将重要信息放在前面；6. 使用Markdown文件而非HTML；7. 生成llms.txt文件；8. 将文档喂给AI工具测试，并评估其准确性；9. 使用Mintlify的agent score评估。
