为REST API构build在线文档
我正在构build我的第一个Rest API,它将数据序列化为JSON和XML格式。 我想为API客户端提供一个索引页面,在那里他们可以select实现的端点。
我需要包含哪些信息才能使我的API最有用,以及如何组织它?
对于一个简单的答案,这是一个非常复杂的问题。
您可能需要查看现有的API框架,如Swagger Specification( OpenAPI )以及像apiary.io和apiblueprint.org这样的服务。
另外,下面是以三种不同方式描述,组织和甚至devise相同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文档至less需要以下内容:
- 所有API端点列表(基本/相对URL)
- 对应每个端点的HTTP GET / POST / …方法types
- 请求/响应MIMEtypes(如何编码参数和parsing答复)
- 一个示例请求/响应,包括HTTP标头
- 为所有参数指定的types和格式,包括URL,正文和头文件中的参数
- 简要的文字描述和重要的注释
- 一个简短的代码片段,显示在stream行的networking编程语言中使用端点
还有很多基于JSON / XML的文档框架可以parsing您的API定义或模式,并为您生成一组方便的文档。 但是文档生成系统的select取决于你的项目,语言,开发环境和其他许多东西。