我正在构建我的第一个Rest API，它将数据序列化为JSON和XML格式 . 我想为API客户端提供一个索引页面，他们可以在这里选择已实现的 endpoints .
我需要提供哪些信息才能使我的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 endpoints 列表（基本/相对URL）
每个 endpoints 的相应HTTP GET / POST / ...方法类型
请求/响应MIME类型（如何编码params和解析回复）
示例请求/响应，包括HTTP标头
为所有参数指定的类型和格式，包括URL，正文和 Headers 中的参数
简要的文字说明和重要说明
一个简短的代码片段，显示了流行的Web编程语言中 endpoints 的使用
此外，还有许多基于JSON / XML的doc框架可以解析您的API定义或模式，并为您生成一组方便的文档 . 但是，doc生成系统的选择取决于您的项目，语言，开发环境和许多其他事情 .
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 endpoints 列表（基本/相对URL）
每个 endpoints 的相应HTTP GET / POST / ...方法类型
请求/响应MIME类型（如何编码params和解析回复）
示例请求/响应，包括HTTP标头
为所有参数指定的类型和格式，包括URL，正文和 Headers 中的参数
简要的文字说明和重要说明
一个简短的代码片段，显示了流行的Web编程语言中 endpoints 的使用
此外，还有许多基于JSON / XML的doc框架可以解析您的API定义或模式，并为您生成一组方便的文档 . 但是，doc生成系统的选择取决于您的项目，语言，开发环境和许多其他事情 .