配置“测试它”按钮

你可以使用多个 OpenAPI 扩展在 GitBook 中配置“测试它”按钮及其对应窗口。这些扩展可以帮助改进并配置用户的测试套件。

隐藏“测试它”按钮

你可以通过添加 x-hideTryItPanel 到某个端点，或添加到你的 OpenAPI 规范根级别，来隐藏该端点的“测试它”按钮。

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: 示例摘要
      description: 示例描述
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

代理“测试它”请求

某些 API 会阻止浏览器请求，通常是因为 CORS。

路由 测试它 通过添加 x-enable-proxy 到你的规范中来通过 GitBook 转发流量。

参见 使用 OpenAPI 代理 获取示例。

在测试窗口中启用身份验证

如果你的规范声明了身份验证，请求运行器才能显示并应用它。在 components.securitySchemes下定义方案，然后通过 security 将它们全局附加（适用于所有操作）或按操作附加（覆盖全局设置）。

声明你的身份验证方案

下面是一些常见模式。在 YAML 中使用直引号。

HTTP Bearer（例如 JWT）

openapi: '3.0.3'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

请求头中的 API Key

OAuth2（authorizationCode）

全局或按操作应用方案

全局

openapi: '3.0.3'
security:
  - bearerAuth: []
paths: ...

按操作

使用以下方式控制端点 URL servers

请求运行器会定位到你在 servers 数组中定义的 URL。声明一个或多个服务器；你也可以使用变量对其进行参数化。

单个服务器

openapi: '3.0.3'
servers:
  - url: https://instance.api.region.example.cloud

多个服务器

服务器变量

按操作设置服务器