为REST API构build在线文档

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

我需要包含哪些信息才能使我的API最有用,以及如何组织它?

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

您可能需要查看现有的API框架,如Swagger Specification( OpenAPI )以及像apiary.io和apiblueprint.org这样的服务。

另外,下面是以三种不同方式描述,组织和甚至devise相同REST API的示例。 从现有的常用方式学习可能是一个好的开始。

在最顶层,我认为高质量的REST API文档至less需要以下内容:

  • 所有API端点列表(基本/相对URL)
  • 对应每个端点的HTTP GET / POST / …方法types
  • 请求/响应MIMEtypes(如何编码参数和parsing答复)
  • 一个示例请求/响应,包括HTTP标头
  • 为所有参数指定的types和格式,包括URL,正文和头文件中的参数
  • 简要的文字描述和重要的注释
  • 一个简短的代码片段,显示在stream行的networking编程语言中使用端点

还有很多基于JSON / XML的文档框架可以parsing您的API定义或模式,并为您生成一组方便的文档。 但是文档生成系统的select取决于你的项目,语言,开发环境和其他许多东西。