OpenStack API 文档¶

developer.openstack.org 的源文件¶

developer.openstack.org 网站旨在供使用 OpenStack API 构建应用程序的开发者使用。它包含指向特定编程语言的多个 SDK 的链接。API 参考和 API 指南存储在 docs.openstack.org 上。developer.openstack.org docs.openstack.org

对于现有的 API，参考信息来自 RST 和 YAML 源文件。RST 和 YAML 文件存储在您的项目仓库中的 api-ref 目录中。nova 项目提供了一个您可以遵循的示例，包括运行 api-ref 目录中的 tox -e api-ref 的 tox 作业来生成文档。

RST 概念和操作指南文件存储在每个项目的 doc/source/api-guide 目录中。这些构建到基于服务名称的位置，例如 Compute API 指南 https://docs.openstack.org/api-guide/compute。

如果您希望生成参考信息，可以在源代码中嵌入注释。这里有一个 nova 项目的示例补丁 https://review.opendev.org/#/c/233446/。由于没有项目具有完整的注释，因此没有针对此场景的构建作业。

OpenStack 中 API 参考的标准¶

API 工作组制定了 API 文档指南，所有在 OpenStack 中提供 REST API 服务的团队都努力遵循。本文档告诉您应该编写什么以及编写多少。如果您遵循建议的提纲，您的 API 指南将准确完整。

如果您的项目没有任何文档，您可以在 API 文档指南中找到建议的提纲。Compute 项目提供了一些可以遵循的示例

对于服务名称，您必须遵守治理仓库中 reference/projects.yaml 文件中指示的服务的官方名称。这些名称用于文档的 URL，通过在 api-ref-jobs 指示符中说明内容的 target 目录来使用。如果您的服务在治理仓库中没有名称，请咨询您的 PTL 或技术委员会成员以了解如何进行。

API 参考信息的版本和发布¶

所有 API 参考作业都会从 master 发布，只要更改降落在各自的项目仓库中。这种发布实践意味着，当 API 发生版本间更改时，您必须编写内联信息。内联文本描述是向文档使用者传达相应发布信息的唯一方法。

与提供 API 的 OpenStack 服务相关联的不同类型的版本。例如，服务的版本与该服务提供的 API 的版本是分开的。此外，微版本 https://docs.openstack.org/api-guide/compute/microversions.html 是对单个 API 方法的小型、文档化的更改，仅适用于某些 OpenStack API，如 API 快速入门页面 https://docs.openstack.org/api-quick-start/ 中所示。

OpenStack Compute 服务版本的示例表示

Header 版本：OpenStack-API-Version: compute 2.1
服务版本（发布名称）：15.0 (Newton)
URI 版本：https://servers.api.openstack.org/v2.1/
MIME 类型版本：application/vnd.openstack.compute.v2.1+json
微版本：2.6

遵循 cycle-with-milestones 发布模型的每个项目都具有包含特定时间点的 API 参考内容的稳定分支。如果需要，请参考该源仓库的内容以进行 API 参考信息的发布比较。

如何记录您的 OpenStack API 服务¶

如果您当前没有任何文档，或者希望将其更新为符合 OpenStack 标准，请使用以下说明。

基本步骤是

在您的项目仓库中创建一个 api-ref/source 目录。

创建一个 conf.py 文件，用于项目，类似于 nova 示例 https://github.com/openstack/nova/blob/2025.2/api-ref/source/conf.py。在其中，包括 html 主题、openstackdocstheme，使用 os-api-ref Sphinx 扩展，并将错误报告链接指向您的项目仓库

extensions = [
    'os_api_ref',
    'openstackdocstheme'
]

# The prefix and repo name like
repository_name = 'openstack/glance'
# Set Launchpad bug tag, default is empty
bug_tag = ''
# The launchpad project name like
bug_project = 'glance'

html_theme = 'openstackdocs'
html_theme_options = {
    "sidebar_mode": "toc",
}

使用 os-api-ref Sphinx 扩展更新项目的 test-requirements.txt 文件
```
os-api-ref>=1.0.0 # Apache-2.0
```
为每个操作创建 RST 文件。
在 RST 文件中，对每个操作使用 .. rest_method::。

示例：.. rest_method:: GET /v2.1/{tenant_id}/flavors

在 RST 文件中，添加指向 parameters.yaml 文件的请求和响应

.. rest_parameters:: parameters.yaml

   - tenant_id: tenant_id

这里是 parameters.yaml 中的一个示例条目

admin_tenant_id:
  description: |
    The UUID of the administrative project.
  in: path
  required: true
  type: string

创建示例 JSON 请求和响应并将其存储在目录中，并在 RST 文件中指向它们。例如
```
.. literalinclude:: samples/os-evacuate/server-evacuate-resp.json
   :language: javascript
```

更新项目的 tox.ini 文件以包含使用以下行在本地构建 API 参考的配置

[testenv:api-ref]
# This environment is called from CI scripts to test and publish
# the API Ref to docs.openstack.org.
whitelist_externals = rm
commands =
  rm -rf api-ref/build
  sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html

通过运行此 tox 命令来测试 tox.ini 更改
```
$ tox -e api-ref
```
将 api-ref-jobs 模板添加到您的项目中，修补存储在 openstack/project-config 仓库中的 zuul.d/projects.yaml 文件 https://opendev.org/openstack/project-config/src/branch/2025.2/zuul.d/projects.yaml。

在源文件和构建作业存在之后，文档将构建到 docs.openstack.org。

如果您的文档完全是新的，您需要从 API 登录页面和 OpenStack 治理参考文档 projects.yaml 添加指向它的链接。

要将链接添加到项目的 API 文档到 API 登录页面，请修补存储在 openstack/api-site 仓库中的 index.rst 文件 https://opendev.org/openstack/api-site/src/branch/2025.2/api-quick-start/source/index.rst。

为了确保 openstack/governance 仓库具有指向您的 API 文档的正确链接，请修补存储在 openstack/governance 仓库中的 reference/projects.yaml 文件 https://opendev.org/openstack/governance/src/branch/2025.2/reference/projects.yaml。

OpenStack API 文档

OpenStack API 文档¶

developer.openstack.org 的源文件¶

OpenStack 中 API 参考的标准¶

API 参考信息的版本和发布¶

如何记录您的 OpenStack API 服务¶

文档贡献者指南

页面内容