一个API的文档的完整性决定了它的有用程度。在编写REST API的文档时，采用标准的程序来创建一个对所有读者来说都更直接的阅读和理解的手册。一个快速参考指南涵盖了你需要了解的关于API的一切，包括程序、类别、结果种类、参数等信息，是由REST API的文档来实现的。本文将指导你了解REST APIs，如何编写REST APIdocs以及编写文档的技巧和工具。
关于REST APIs
REST APIs使各种互联网应用程序之间的通信更加容易。在利用一个程序时，你可以从另一个程序获得数据。你可以使用RESTful API，而不是传统的方法，因为传统的方法需要更长的时间，而且安全性较低。使用API，你可以从一个系统中获得数据，而不需要参与用户界面。
REST是一种流行的架构设计和编程方法，用于网络超媒体平台和其他网络技术。例如，当程序员要求获得客户的对象时，Instagram的API将返回用户的状态、身份、连接和共享推文。由于API的整合，这一点是可行的。
如何编写API文档？
更好的文档应该既是一个指南，又是一个教育工具，使开发者能够快速找到他们需要的细节，一目了然，并通过查阅文档了解如何纳入他们正在考虑的技术。因此，适当的文档必须既简明又明显，提供以下内容。
- 对该技术或项目的详细描述
- 向开发者传达关键细节的呼号，如问题和注意事项
- 一个带有相应媒体类型内容的调用示例
- 该技术使用的变量清单，以及关于其种类、特殊结构要求和是否需要的信息。
- 一个带有媒体类型body的响应的例子
- 包含所有必要代码的几种语言的脚本样本（如Java、.Net、Ruby等）。
- SDK实例
- 它们演示了如何使用其方言的SDK来达到服务或程序。
- 测试和尝试API请求的有价值的活动（API控制台、API笔记本)
- 询问和带有代码的情况是常见的问题。
- 相关网站的参考资料（其他的例子，博客等）。
编写RESTful API文档的最佳技巧
规划你的文档编写策略
当开始写文档的时候，你必须做一个彻底的策略。你成功的概率会因此而上升。在你记录REST API之前，了解你为之创建文档的读者。如果你知道你的目标读者，你可以很容易地为你的文档选择合适的平台、风格和布局。
如果你清楚地掌握了记录REST API的目标和范围，你就会更容易制作出相关的材料，从而提高你的API的使用率。你可以在编写REST API时考虑到用户的要求，从而组织文档，更好地满足用户的要求。
记住，消费者在使用你的API时，对你的操作场景有一个心理暗示。例如，用户可能会考虑API文档的成本、回报、客户和借记卡，如果你提供支付方式的话。
因此，以这种方式组织你的文档使其符合逻辑。考虑研究一下Stripe API的文档。他们在对API进行逻辑分组之前给出了一个体面的介绍。GitHub为RESTful API文档提供了一个坚实的说明，它组织良好，有 "GitHub信息、问题和成员 "部分。
GitHub允许你创建拉动请求、分支等。GitHub的API文档是开源的。GitHub最棒的地方在于，它一直在努力以重要的方式改善开发者的体验。
包括基本部分
优秀的RESTful API文档必须包括一定数量的部分。这样的核心部分在增强REST API文档的清晰度和提高其接受度方面至关重要。在记录REST API时，你应该考虑一些基本要素。
- 对REST API的介绍
- 如何获得用户凭证
- 使用API时需要的资源
- 与API通信时的错误信息
- 使用条款
保持完整性，避免使用专业术语
全文中术语使用的一致性是RESTful API文档的另一个有用方法。使用一致的写作风格，没有语言和编码上的不一致。在彻底校对你的内容后，删除任何不清楚或难以理解的部分。
始终使用一致的术语和词汇标准。在使用HTTP协议、状态代码和其他可能导致误解的普通项目名称时，发挥你的想象力。例如，在描述REST APIs时，应该使用GET HTTP动词来查询指定资源的数据。如果你坚持使用已知的规范，你就不需要写很多理由，而且你的文件也会更简单易读。如果你在你的API描述中也避免过度使用技术语言，这将会有所帮助。确保使用直截了当的语言来表达你核心受众的要求。
添加交互式插图
大多数开发者喜欢测试他们在文档中读到的东西，以确定它是否有效。在大多数开发者都熟悉的编程语言中，包括动态的示例程序。这将使API开发不那么复杂。
包括动态REST API例子是一种有效的技术，可以在利用你的API时降低学习曲线。此外，你还可以包括测试信息，用户可以用它来提交建议，并检查他们收到的答复的种类。
在记录REST API的时候，你可以包括除现场例子以外的材料。这将帮助用户在说明中提供的信息之外充分利用API。账户设置指南、框架、开发工具和研讨会是一些可以用来增强API描述的材料。
为入门级的职位而写
专业写手，而不是开发者，经常产生文档。这是因为技术作家专门将技术概念解释为可理解的语言。然而，许多技术作家在他们的手册中使用技术词汇。每个API的开发都考虑到了特定的受众。
API文档有广泛的浏览者，包括开发者、判断团队和观察者。开发人员参与到文档中。判断团队，如工程师和CTO，快速了解API是否合适，还有旁观者，如技术作家、记者和你的对手。
这些人有不同的职责和才能，在查看你的REST API文档时应该放松。因此，你应该专注于最没有经验的消费者。在记录REST API时，应用上述技巧，以保证REST API的文件能被具有不同程度API知识的人所理解。
生成RESTful API文档的最佳工具
使用Restful APIs的工具，技术文档的方法已经被简化。技术作家如果熟悉编码，可以使用这些RESTAPI文档工具来创建技术出版物。由于API文档制作者的使用很广泛，下面包括最著名的制作者是免费的，并且支持OpenAPI v3。技术作家使用这些资源来制作REST API文档。
SwaggerHub
SwaggerHub 是一个数字API文档平台，为简化和加快Rest API文档而创建，使其成为团队和企业的完美选择。你可以更快速地遵守OpenAPI规范（ ），以前称为 ，采用API编辑器。OAS Swagger
它的一些特点是。
- 有效的错误报告和自动完成的语言
- 持续执行标准的综合API设计指南
- 用于存储和利用跨API通用的OAS语法的网站
- 实时的问题跟踪和评论
- 提供优秀的开发者体验
Redocly
REST API文档的过程是使用Redocly's Workflows解决方案自动化的。你可以像处理程序代码一样处理你的文档，使用虚拟化的文档，将其保存在特别版软件中，建立一个审计程序，并将其交付给各种设置。Redocly'的用户权限、尝试验证和其他认证机制使你能够进一步保证你的团队有效和安全地一起工作。 Redocly 的显示能力是另一个独特的功能。为了确保你的修改在发送给公众之前得到评估和辩论，你可以预览每个项目和补丁请求。
Stoplight
使用Stoplight's REST API写作工具，你可以以数字方式建立和提供API文档。利用这个软件，你可以生成动态的REST API文档，可以在内部和外部向公众发布。你可以把用各种编程语言（如JavaScript、Python和Java）创建的如何使用文章、指导手册和代码样本纳入其中。
你可以在Stoplight上发布你的文档，这是我们REST API文档解决方案的重要功能之一。这使你不必担心操作服务器，并使你能简单地使用连接器来处理权限和跟踪度量。
ReadMe
你的API文档可以通过ReadMe ，成为你的开发人员的动态中心。他们可以自动创建代码示例，改变ReadMe编辑器中的材料，整合推荐的编辑，回应讨论区的询问，以及在这个中心的更多。
ReadMe'最显著的好处之一是，它可以分析页面访问、API请求、API失败和对各种网站的查询等分析，因此你可以看到你的应用编程接口和REST API文档是如何随着时间的推移被使用的。利用这些指标，你的工作人员可以确定在哪里集中精力进行改进。
apiDoc
一个名为apiDoc 的开源REST API文档解决方案可以从包含API细节的代码库中生成文档。它几乎与每一种编程语言都兼容。工程师们可以观察一个API版本之间的修改内容，因为apiDoc ，你可以这样做。这有利于干净利落地处理API的更新，通常被称为API版本管理。
DapperDox
DapperDox 编写RESTful API文档的人为REST API文档编写者开发的，目的是给编写者以他们想要的自由，给开发者以他们需要的可读性。这个web API docs解决方案是生成一个连贯的文档集合的理想选择，其中包含可理解的说明和web API标准，因为它可以让编写者将相关的材料添加到制作的描述网站中。此外，你可以根据需要进行交叉引用，将各种API要求作为一组商品进行描述，并选择主题来对论文进行不同的格式化。
DocGen 通过LucyBot
你可以使用LucyBot'sDocGen 来生成和管理动态API文档。这个程序为每个API方法和参数创建文档，并即时回复。你可以创建一个API控制台，使创建者和用户能够执行试验性的API请求，以检查、排除故障，并从根本上了解你的API。你也可以创建流程，向用户展示他们必须创建的编码以及他们必须遵循的阶段，以完成他们选择的软件语言中的特定工作。
AppMaster
与其他平台不同。 AppMaster消除了开发人员手动创建REST API文档和更新文档的需要。该平台为每个应用程序自动生成和更新REST API文档，格式为Swagger (OpenAPI)，还在每个服务器应用程序中包括Swagger UI，使第三方开发者更容易与生成的应用程序集成。此外，AppMaster 平台在生成REST API文档时，会在每个端点的描述中自动包括端点和相关业务流程的描述，完全不需要开发者创建或更新文档。
最后的话
本文所涉及的所有API文档工具都能够产生高质量的API文档。不可能宣布任何一个工具是最伟大的。一个API文档软件的全部经验和标准是由客户的标准、概念、目标和文档要求决定的。
