indexing - 构建 REST API 的在线文档

Question

我正在构建我的第一个 Rest API，它将数据序列化为 JSON 和 XML 格式。我想向 API 客户端提供一个索引页面，他们可以在其中选择已实现的端点。

我需要包含哪些信息才能使我的 API 最有用，以及我应该如何组织它？

Answer 1

这是一个非常复杂的问题，但答案很简单。

您可能想看看现有的 API 框架，例如 Swagger规范 ( OpenAPI )，以及类似 apiary.io 的服务和 apiblueprint.org .

此外，这里还有一个以三种不同方式描述、组织甚至设计样式的相同 REST API 的示例。对您来说，学习现有的常用方法可能是一个好的开始。

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

在最顶层，我认为高质量的 REST API 文档至少需要以下内容:

• 所有 API 端点(基本/相对网址)的列表
• 每个端点对应的 HTTP GET/POST/... 方法类型
• 请求/响应 MIME 类型(如何编码参数和解析回复)
• 示例请求/响应，包括 HTTP header
• 为所有参数指定的类型和格式，包括 URL、正文和 header 中的参数
• 简短的文字描述和重要说明
• 显示端点在流行网络编程语言中的使用的简短代码片段

还有很多基于 JSON/XML 的文档框架，可以解析您的 API 定义或架构，并为您生成一组方便的文档。但文档生成系统的选择取决于您的项目、语言、开发环境和许多其他因素。