> 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/using-openapi-proxy.md).

# 使用 OpenAPI 代理

GitBook 可以代理 **测试它** 请求，因此即使你的 API 服务器不支持 CORS，它们也能正常工作。

### 这样做的原因

浏览器会阻止跨域请求，除非 API 服务器通过 CORS 头部明确允许。若未配置 CORS， **测试它** 这些请求会在浏览器中失败。代理会通过 GitBook 在服务端转发这些请求，从而绕过该限制。

### 为整个规范启用代理

添加 `x-enable-proxy: true` 到你的 OpenAPI 规范根部。

<pre class="language-yaml"><code class="lang-yaml">openapi: '3.0.3'
<strong>x-enable-proxy: true
</strong>info:
  title: 示例 API
  version: '1.0.0'
servers:
  - url: https://api.example.com
</code></pre>

### 为特定操作启用或禁用

添加 `x-enable-proxy` 在某个操作上。

<pre class="language-yaml"><code class="lang-yaml">openapi: '3.0.3'
info:
  title: 示例 API
  version: '1.0.0'
servers:
  - url: https://api.example.com
paths:
  /reports:
    get:
      summary: 列出报告
<strong>      x-enable-proxy: true
</strong>      responses:
        '200':
          description: 成功
    post:
      summary: 创建报告
<strong>      x-enable-proxy: false
</strong>      responses:
        '201':
          description: 已创建
</code></pre>

{% hint style="info" %}
操作级别 `x-enable-proxy` 优先于根级值。
{% endhint %}

### 代理支持的内容

GitBook 会转发所有 `HTTP` 方法（`GET`, `POST`, `PUT`, `DELETE`, `PATCH`）、请求头、Cookie 和请求体。

### 安全性

代理只会将请求转发到你的规范中列出的 URL `servers` 数组。它不能用于访问任意 URL。

{% hint style="info" %}
请确保你的 `servers` 数组包含你想要测试的每个基础 URL。如果某个 URL 未列出， **测试它** 对该主机的请求将绕过代理。
{% endhint %}


---

# 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/using-openapi-proxy.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.