交互式 API 文档

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

有关极狐GitLab API 的一般信息，请参阅使用极狐GitLab 扩展。

交互式 API 文档工具允许直接在 JihuLab.com 网站上进行 API 测试。虽然只有少数可用的端点用 OpenAPI 规范进行了记录，但当前的列表展示了该工具的功能。

端点参数#

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

开始交互式会话#

个人访问令牌（PAT）是开始交互式会话的一种方式。为此，从主页选择授权，然后一个对话框会提示您输入 PAT，该 PAT 对当前的网页会话有效。

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

愿景#

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

为实现这一目标，应该要求在每次 API 代码变更时更新 OpenAPI 规范。通过这样做，我们确保文档始终是最新的和准确的，从而降低用户的混淆和错误风险。

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

您可以在 Document the REST API in OpenAPI V2 epic 中关注此愿景的当前进展。