如果API正在吃世界（如信息周三建议），您可以将API文档视为食谱，这是使您的API易于理解和易于使用的重要组成部分。正如厨师依靠书面食谱一样创造出美妙的菜肴，您需要创建一个信息，简洁，易于阅读的API文档，所以其他开发人员可以使用您的API烹饪美妙的东西。
安迪威尔金森那春天IO平台云天然平台公司领导枢轴，在他的演示文稿中提供了伟大的提示“记录RESTFUL API”springone2gx.上个月在华盛顿州，D.C.。通过难以赢得的经验，这里有一些提示Andy提供帮助您创建Restful API文档您的用户会喜欢。
1.您的代码时帮助自己
良好的设计决策使您更轻松地记录您的API。始终如一！如果您可以在命名约定中保持一致，并且牢记具有现有行为标准，您只需要记录一次物品一次......完全！例如，对于HTTP状态代码：不要弯曲意义，不要添加新代码：“不要强迫用户了解世界略微古怪的视图。”不要离开殴打路径：200表示确定。404意味着找不到。
对于HTTP动词，相同的保留：使用POST创建，删除删除。这些是完善的惯例，以自己的风险违反他们。一个例外：放置和补丁。这些文件不清楚（良好的RFC运气），不同的应用程序对它们具有不同的解释。一些API制作并补丁代名词;只要对您的特定用途清楚。（您可以在此StackOverflow讨论中找到更多信息：补丁和提出请求之间的主要区别是什么？）
2.来自用户的角度的文档
请记住，用户使用您正在使用的上下文的心理模型来到您的API。例如，如果您提供支付处理器，则用户正在考虑费用，退款，客户和信用卡。因此，这种方式构建文档是有意义的。例如，看看条纹API文档。它们以逻辑的方式提供了一个很好的介绍，然后是组API。GitHub提供了良好组织的良好示例RESTFEP API文档，与Git数据等分组，提取请求，问题和用户。
3.不要让你的前沿和中心
您的文档中最明显的事情使用户要求用户弄清楚逻辑和HTTP客户端之间的映射。此外，许多用户将难以代码URI，如果您使用超媒体控件，则会破坏客户端，然后更改它们。这是OFT使用的文档工具的最大缺点昂首阔步。Swagger很受欢迎，因为它提供了很多努力，但它会生成一个以Uri为中心的文档。例如，VFABRIC管理服务器REST API文档受到昂首阔步的启发。因为URI是如此突出并且结构差，所以这篇文档可能是准确的，但它并不是非常有帮助的。这是Andy提供的例子，因为他帮助创建了这些文档，并从经验中学到了一些艰苦的教训。
4.写入写作工具
尽可能多地用设计用于写作的格式。“在注释中写入文档是可怕的，”安迪解释说。考虑一个工具，如asciidoctor.，用于创作文档，笔记，书籍以及出版工具链的纯文本写作格式。ASCIIDOCTOR还有一个巨大的生态系统，包括许多有用的插件。
5.自动生成示例并将其与您的解释组合
安迪创造了春休息文档项目帮助用户获取他们需要的信息，最少的大惊小怪。它结合了用ASCIIDOCTOR编写的手写文档和使用的自动生成的片段Spring MVC测试。这种组合击中了自动化和手动生成的信息之间的甜点。
6.计划未来
看着那（这理查德森成熟模型确定您的API实际上有多宁静。如果您的代码更靠近（或者您计划使其更靠近您的工具），您的文档工具可以限制您。不要自己盒子。你计划达到3级并使用超媒体吗？然后确保您的工具将支持。
作为infoweek.托马斯·克拉伯恩解释说：“API让一些人能够以极大的努力和投资提供全世界可信的服务。”为了确保您的伟大想法被其他开发人员使用，良好的API文档应始终成为您努力的一部分。
