配置“测试它”按钮

您可以在 GitBook 中使用多个 OpenAPI 扩展来配置“测试它”(Test It) 按钮及其附带窗口。这些扩展可以帮助改进并配置用户的测试套件。

隐藏“测试它”按钮

您可以通过在端点或 OpenAPI 规范的根处添加 x-hideTryItPanel 来从端点隐藏“测试它”按钮。

openapi.yaml

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

在测试窗口中启用认证

请求运行器只有在您的规范声明了认证时才能呈现并应用认证。请在下方定义方案 components.securitySchemes，然后将它们附加为全局（通过 security ）（适用于所有操作）或按单个操作附加（覆盖全局设置）。

声明您的认证方案

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

HTTP Bearer（例如 JWT）

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

Header 中的 API Key

openapi: '3.0.3'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

OAuth2（authorizationCode）

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: ...

按操作

paths:
  /reports:
    get:
      summary: 获取报告
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: OK

使用 servers 控制端点 URL servers

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

单个服务器

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

多个服务器

servers:
  - url: https://api.example.com
    description: 生产环境
  - url: https://staging-api.example.com
    description: 预发布环境

服务器变量

servers:
  - url: https://{instance}.api.{region}.example.cloud
    variables:
      instance:
        default: acme
        description: 您的租户或实例标识符
      region:
        default: eu
        enum:
          - eu
          - us
          - ap
        description: 区域部署

按操作的 servers

paths:
  /reports:
    get:
      summary: 获取报告
      servers:
        - url: https://reports.api.example.com
      responses:
        '200':
          description: OK