问构建REST API的在线文档

EN

对于一个简单的答案来说，这是一个非常复杂的问题。

你可能想看看现有的Swagger框架，比如API (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所有URLs)

• corresponding端点的列表(基础/相对API//...每个endpoint
• request/response MIME类型的方法类型(如何编码参数和解析回复)
• 一个示例请求/响应，包括为所有参数指定的HTTP头
• 类型和格式，包括URL、body和headers中的那些
• 简短的文本说明和重要说明
• 显示在流行的web编程语言中使用端点的简短代码片段

<代码>F230

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