> 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/managing-api-operations.md).

# 管理 API 操作

了解如何将 OpenAPI API 操作标记为实验性、已弃用，或将其从文档中隐藏

出现尚未完全稳定或需要逐步淘汰的操作很常见。GitBook 支持多种 OpenAPI 扩展，帮助你管理这些情况。

### 将操作标记为 experimental、alpha 或 beta

使用 `x-stability` 用于说明某个端点不稳定或仍在开发中。它可以帮助用户避免使用尚未适用于生产环境的端点。支持的值： `experimental`, `alpha`, `beta`.

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths:
  /pet:
    put:
      operationId: updatePet
<strong>      x-stability: experimental
</strong></code></pre>

### 将操作标记为废弃

要将一个操作标记为已废弃，请添加 `deprecated: true` 属性。

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths:
  /pet:
    put:
      operationId: updatePet
<strong>      deprecated: true
</strong></code></pre>

你也可以通过添加以下内容来指定支持何时结束 `x-deprecated-sunset`

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths:
  /pet:
    put:
      operationId: updatePet
<strong>      deprecated: true
</strong><strong>      x-deprecated-sunset: 2030-12-05
</strong></code></pre>

### 在 API 参考中隐藏一个操作

要在 API 参考中隐藏一个操作，请添加 `x-internal: true` 或 `x-gitbook-ignore: true` 属性。

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths:
  /pet:
    put:
      operationId: updatePet
<strong>      x-internal: true
</strong></code></pre>

### 隐藏响应示例

添加 `x-hideSample: true` 属性到响应对象中，以将其从响应示例部分排除。

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths:
  /pet:
    put:
      operationId: updatePet
<strong>      responses:
</strong><strong>        200:
</strong><strong>          x-hideSample: true
</strong></code></pre>

### 自定义授权前缀和令牌占位符

你可以自定义授权前缀（例如， `Bearer`, `Token`，或者自定义字符串）以及在 GitBook 中使用安全方案时显示的令牌占位符。

在你的 OpenAPI 规范中，在 `components.securitySchemes`下，像这样定义你的方案：

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">components:
  securitySchemes:
    apiKey：
      type: apiKey
      in: header
      name: Authorization
<strong>      x-gitbook-prefix: Token
</strong><strong>      x-gitbook-token-placeholder: YOUR_CUSTOM_TOKEN
</strong></code></pre>

这些扩展：

* `x-gitbook-prefix` 定义添加在令牌前面的前缀。
  * 示例： `Authorization: <x-gitbook-prefix> YOUR_API_TOKEN`
* `x-gitbook-token-placeholder` 设置默认令牌值。
  * 示例： `Authorization: Bearer <x-gitbook-token-placeholder>`

{% hint style="warning" %}
`x-gitbook-prefix` 不 `http` 支持用于安全方案，因为这些方案必须遵循标准的 IANA 身份验证定义。 [了解更多](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml)
{% 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/managing-api-operations.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.