# 配置“测试它”按钮

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

### 隐藏“测试它”按钮

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

{% code title="openapi.yaml" %}

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

{% endcode %}

### 代理“测试它”请求

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

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

参见 [使用 OpenAPI 代理](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/api-references/guides/using-openapi-proxy) 获取示例。

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

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

#### 声明你的身份验证方案

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

{% tabs %}
{% tab title="HTTP Bearer（例如 JWT）" %}

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

{% endtab %}

{% tab title="请求头中的 API Key" %}

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

{% endtab %}

{% tab title="OAuth2（authorizationCode）" %}

```yaml
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: '写入项目'
```

{% endtab %}
{% endtabs %}

#### 全局或按操作应用方案

{% tabs %}
{% tab title="全局" %}

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

{% endtab %}

{% tab title="按操作" %}

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

{% endtab %}
{% endtabs %}

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

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

{% tabs %}
{% tab title="单个服务器" %}

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

{% endtab %}

{% tab title="多个服务器" %}

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

{% endtab %}

{% tab title="服务器变量" %}

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

{% endtab %}

{% tab title="按操作设置服务器" %}

<pre class="language-yaml"><code class="lang-yaml"><strong>paths:
</strong>  /reports:
    get:
      summary: 获取报告
      servers:
        - url: https://reports.api.example.com
      responses:
        '200':
          description: OK
</code></pre>

{% endtab %}
{% endtabs %}