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

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