如果 API 正在吞噬世界（正如 InformationWeek 所建议的 那样），您可以将 API 文档视为食谱，这是使您的 API 易于理解和易于使用的关键部分。正如厨师依靠精心编写的食谱来制作美味佳肴一样，您需要创建内容丰富、简洁且易于阅读的 API 文档，以便其他开发人员可以使用您的 API 烹制出美味佳肴。
Andy Wilkinson 是云原生平台公司 Pivotal 的 Spring IO 平台 负责人，上个月在华盛顿特区的 SpringOne2GX 上他的演讲“记录 RESTful API”中提供了很好的技巧。通过来之不易的经验获得，这里是 Andy 提供的一些技巧，可帮助您创建用户喜欢的 RESTful API 文档。
1. 编码时帮助自己
良好的设计决策可以更轻松地记录您的 API。始终如一！如果您可以在命名约定方面保持一致并坚持现有的行为标准，那么您只需为一个项目记录一次……如果有的话！例如，对于 HTTP 状态代码：不要扭曲含义，不要添加新代码：“不要强迫用户理解你稍微古怪的世界观。”不要偏离常规：200 表示还可以。 404 表示未找到。
HTTP 动词也是如此：使用 POST 来创建，使用 DELETE 来删除。这些是公认的惯例，违反它们后果自负。一个例外：PUT 和 PATCH。这些文档不清楚（祝 RFC 好运），不同的应用程序对它们有不同的解释。一些 API 使 PUT 和 PATCH 成为同义词；只需清楚您的特定用法即可。 （您可以在此 StackOverFlow 讨论中找到更多信息： PATCH 和 PUT 请求之间的主要区别是什么？ ）
2. 用户视角的文档
请记住，用户使用您的 API 时会产生您所处环境的心智模型。例如，如果您提供支付处理器，用户会考虑收费、退款、客户和信用卡。因此，以这种方式构建文档是有意义的。例如，查看 Stripe API 文档 。他们提供了很好的介绍，然后以合乎逻辑的方式对 API 进行分组。 GitHub 提供了组织良好的 RESTful API 文档 的很好示例，其中包含 Git 数据、拉取请求、问题和用户等分组。
3. 不要把 URI 放在前面和中间
使 URI 成为您文档中最明显的东西需要用户弄清楚您的逻辑和 HTTP 客户端之间的映射。此外，许多用户会对 URI 进行硬编码，如果您使用超媒体控件然后更改它们，这将破坏客户端。这是经常使用的文档工具 Swagger 的最大缺点。 Swagger 之所以流行，是因为它提供了很多功能而不费太多力气，但它生成的文档是以 URI 为中心的。例如， vFabric Administration Server REST API 文档的 灵感来自 Swagger。由于 URI 非常突出并且结构很差，因此该文档可能是准确的，但并不是很有帮助。这是 Andy 提供的示例，因为他帮助创建了这些文档，并从中吸取了一些惨痛的教训。
4. 用书写工具书写
尽可能多地以专为写作设计的格式写作。 “在注释中编写文档是可怕的，”安迪解释道。考虑一个工具，如 ASCIIDoctor ，一种用于编写文档、笔记、书籍以及发布工具链的纯文本书写格式。还有一个围绕 ASCIIDoctor 的巨大生态系统，其中包括许多有用的插件。
5. 自动生成示例并将它们与您的解释相结合
Andy 创建了 Spring REST 文档 项目，以帮助用户轻松获得所需的信息。它结合了使用 ASCIIDoctor 编写的手写文档和使用 Spring MVC Test 生成的自动生成的片段。这种组合在自动化和手动生成的信息之间达到了最佳平衡点。
6. 未来计划
查看 Richardson 成熟度模型 以确定您的 API 的实际 RESTful 程度。如果您的代码比您的工具允许的更 RESTful（或者您计划使其更 RESTful），那么您的文档工具可能会限制您。不要把自己困在里面。你打算达到第 3 级并使用超媒体吗？然后确保你的工具支持它。
正如 InfoWeek 的 Thomas Claburn 所解释的那样，“API 使一些有好主意的人能够以最少的努力和投资在全球范围内提供可靠的服务。”为确保您的好主意被其他开发人员使用，良好的 API 文档应该始终是您努力的一部分。
