我正在构建我的第一个 Rest API,它将数据序列化为 JSON 和 XML 格式。 我想向 API 客户端提供一个索引页面,他们可以在其中选择已实现的端点。
我需要包含哪些信息才能使我的 API 最有用,以及我应该如何组织它?
最佳答案
这是一个非常复杂的问题,但答案很简单。
您可能想看看现有的 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 定义或架构,并为您生成一组方便的文档。但文档生成系统的选择取决于您的项目、语言、开发环境和许多其他因素。
关于indexing - 构建 REST API 的在线文档,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/5757864/