配置“测试它”按钮

您可以在 GitBook 中使用若干 OpenAPI 扩展来配置 “Test It” 按钮及其伴随窗口。这些扩展可以帮助改进并配置面向用户的测试套件。

隐藏 “Test it” 按钮

您可以通过在端点添加 x-hideTryItPanel 到端点或将其放在 OpenAPI 规范的根处，以隐藏端点的 “Test it” 按钮。

openapi.yaml

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

代理 “Test it” 请求

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

通过 GitBook 路由 Test it 流量，通过在规范中添加 x-enable-proxy 到您的规范中。

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

在测试窗口中启用认证

请求运行器只有在您的规范声明了认证时才能展示并应用认证。请在 components.securitySchemes下定义方案，然后通过下列方式将其附加：要么在全局通过 security （适用于所有操作）或每个操作单独（覆盖全局）。

声明您的认证方案

下面是常见模式。在 YAML 中使用直引号（straight quotes）。

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

openapi: '3.0.3'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://auth.example.com/oauth/authorize'
          tokenUrl: 'https://auth.example.com/oauth/token'
          scopes:
            read:items: '读取项目'
            write:items: '写入项目'

在全局或每个操作上应用方案

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

使用 `servers`

来控制端点 URL servers 请求运行器会以您在

openapi: '3.0.3'
单个服务器
  servers:

单个服务器
  服务器变量
    - url: https://{instance}.api.{region}.example.cloud
      variables:
        instance:
        default: acme
      description: 您的租户或实例标识（slug）
        region:
        default: eu
          enum:
          - eu
          - us
        - ap

paths:
  /reports:
    get:
      summary: 获取报告
      单个服务器
        每个操作的服务器配置：
- url: https://reports.api.example.com
      responses:
        '200':
          description: OK

最后更新于12天前

这有帮助吗？