内容¶
首先，您应该生成或编写参考信息，包括
- 方法 (GET/PUT/POST/PATCH/HEAD/DELETE)
- 资源（由 URL 标识）
- 请求参数、类型和描述，包括是否为可选参数
- 请求头，包括 media-type、content-type、accept 以及其他头部
- 响应头（对于某些 API）
- 响应，包括类型和描述
- 示例请求体和头部
- 示例响应体和头部
- 状态码：成功的请求和错误响应
- 资源模型：描述操作可以消耗和生成的数据类型。
资源模型可以使用 parameters.yaml 文件或 OpenAPI Definitions 对象 创建。Swagger 受 OpenAPI 倡议的管理。
有关编写或生成参数信息的更多信息，请参阅下面的创作工具。
同样重要的是概念或叙述性信息，它解释了 REST API 以及它作为服务提供的功能。
文档还应提供有关每个资源的概念信息，例如服务器状态或卷状态。
文档应提供关于服务提供的一致性模型以及某些方法的同步或异步行为的讨论。
作为指导，以下是您在 API 文档中除了参考信息之外，应确保包含的主题列表。
- 身份验证
- 错误（同步和异步）
- 限制（速率限制、绝对限制、查找限制的调用）
- 约束（即使由提供商选择，某些值的最小值和最大值）
- 内容压缩
- 编码
- 链接和引用
- 分页
- 过滤
- 排序
- 格式（请求、响应）
- 端点、版本和可发现性
- 功能和可发现性
- 术语定义（通过添加到 openstack-manuals 中提供的 OpenStack 词汇表）
- 状态或状态值
- 层次信息
- 配额
- 扩展
这些主题应以 RST 编写，并使用 Sphinx 或与下面描述的 Pecan 应用程序生成的 OpenAPI 一起构建。由于 REST API 各不相同，因此提纲本身没有规定。