构建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类型(如何编码params和解析回复)
• 示例请求/响应,包括HTTP标头
• 为所有参数指定的类型和格式,包括URL,正文和标题中的参数
• 简短的文字说明和重要说明
• 一个简短的代码片段,显示了在流行的Web编程语言中使用端点的过程

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