为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取决于你的项目，语言，开发环境和其他许多东西。
