构建REST API的在线文档

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

为了使我的API最有用，我需要包括哪些信息？如何组织它？

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

您可能想看看现有的API框架（例如Swagger Specification（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端点（基本/相对URL）的列表
• 每个端点对应的HTTP GET / POST / ...方法类型
• 请求/响应MIME类型（如何编码参数和解析回复）
• 样本请求/响应，包括HTTP标头
• 为所有参数指定的类型和格式，包括URL，正文和标题中的参数
• 简短的文字说明和重要说明
• 一个简短的代码片段，显示流行的Web编程语言中端点的使用

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