交互式 API 文档

OpenAPI 规范（前称 Swagger）为 RESTful API 定义了一个标准的、与语言无关的接口。OpenAPI 定义文件采用 YAML 格式编写，GitLab 浏览器会自动将其渲染成更易于阅读的界面。

有关 GitLab API 的通用信息，请参阅 使用 GitLab 扩展。

交互式 API 文档工具 允许您直接在 GitLab.com 网站上测试 API。目前只有少数可用端点（endpoint）使用 OpenAPI 规范进行了文档化，但当前的列表足以展示该工具的功能。

端点参数

当您展开一个端点列表时，您会看到其描述、输入参数（如果需要）以及示例服务器响应。某些参数包含默认值或允许值的列表。

启动交互式会话

个人访问令牌 (PAT) 是启动交互式会话的一种方式。为此，请在主页上选择 Authorize（授权），系统会弹出一个对话框，提示您输入您的 PAT，该令牌对当前 Web 会话有效。

要测试端点，请首先在端点定义页面上选择 Try it out（试用）。根据需要输入参数，然后选择 Execute（执行）。在下面的示例中，我们执行了一个针对 version 端点的请求（无需任何参数）。该工具会显示请求的 curl 命令和 URL，以及随后返回的服务器响应。您可以通过编辑相关参数，然后再次选择 Execute（执行）来创建新的响应。

愿景

API 代码是唯一的真实来源，API 文档应与其实现紧密耦合。OpenAPI 规范提供了一种标准化且全面的方式来记录 API。它应该成为记录 GitLab REST API 的首选格式。这将带来更准确、可靠和用户友好的文档，从而提升使用 GitLab REST API 的整体体验。

为实现这一目标，应要求每次 API 代码变更时都更新 OpenAPI 规范。通过这样做，我们可以确保文档始终保持最新和准确，从而降低用户产生困惑和错误的风险。

OpenAPI 文档应从 API 代码自动生成，以便轻松保持其更新和准确性。这将为我们的文档团队节省时间和精力。

您可以在 使用 OpenAPI V2 记录 REST API epic 中关注此愿景的最新进展。