> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/openapi/guides/configuring-the-test-it-button.md).

# 配置“测试它”按钮

你可以使用多个 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` 到你的规范中。

参见 [使用 OpenAPI 代理](/docs/documentation/zh/chuang-jian-nei-rong/openapi/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 密钥" %}

```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: 成功
```

{% 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: 你的租户或实例 slug
      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: 成功
</code></pre>

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/openapi/guides/configuring-the-test-it-button.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.