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 中关注此愿景的当前进展。