# 配置“测试它”按钮

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

### 隐藏“Test it”按钮

您可以通过添加 `x-hideTryItPanel` 到某个端点，或到您的 OpenAPI 规范根级别，来隐藏端点中的“Test it”按钮。

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

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

{% endcode %}

### 代理“Test it”请求

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

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

参见 [使用 OpenAPI 代理](/docs/documentation/zh/api-references/guides/using-openapi-proxy.md) 示例。

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

如果您的规范声明了认证，请求运行器才能呈现并应用认证。在 `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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/api-references/guides/configuring-the-test-it-button.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.