构建REST API的在线文档 [英] Structuring online documentation for a REST API

问题描述

我正在构建我的第一个Rest API，它将数据序列化为JSON和XML格式。
我想为API客户端提供一个索引页面，他们可以在这里选择已实现的端点。

I'm building my first Rest API which serialize data to JSON and XML formats. I would like to provide an index page to API clients, where they would be able to choose implemented endpoints.

我需要包含哪些信息才能生成我的API最有用，我应该如何组织它？

What information do I need to include to make my API most useful, and how should I organize it?

推荐答案

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

That's a very complex question for a simple answer.

您可能需要查看现有的API框架，例如 Swagger 规范（ OpenAPI ）和 apiary.io 和 apiblueprint.org 。

You may want to take a look at existing API frameworks, like Swagger Specification (OpenAPI), and services like apiary.io and apiblueprint.org.

此外，这里是以三种不同方式描述，组织甚至设置样式的相同REST API的示例。从现有的常用方法中学习可能是一个良好的开端。

Also, here's an example of the same REST API described, organized and even styled in three different ways. It may be a good start for you to learn from existing common ways.

• https://api.coinsecure.in/v1


• https://api.coinsecure.in/v1/originalUI


• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

• 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文档至少需要以下内容：

At the very top level I think quality REST API docs require at least the following:

• 所有API端点列表（基本/相对URL）


• 每个端点的相应HTTP GET / POST / ...方法类型


• 请求/响应MIME类型（如何编码参数和解析回复）


• 示例请求/响应，包括HTTP标头


• 指定的类型和格式f或所有参数，包括URL，正文和标题中的参数


• 简短的文字说明和重要说明


• 一个简短的代码片段，显示了流行的Web编程语言中的端点

• a list of all your API endpoints (base/relative URLs)
• corresponding HTTP GET/POST/... method type for each endpoint
• request/response MIME-type (how to encode params and parse replies)
• a sample request/response, including HTTP headers
• type and format specified for all params, including those in the URL, body and headers
• a brief text description and important notes
• a short code snippet showing the use of the endpoint in popular web programming languages

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

Also there are a lot of JSON/XML-based doc frameworks which can parse your API definition or schema and generate a convenient set of docs for you. But the choice for a doc generation system depends on your project, language, development environment and many other things.

这篇关于构建REST API的在线文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！