# 管理 API 操作

对于尚未完全稳定或需要逐步弃用的操作，这是很常见的。GitBook 支持若干 OpenAPI 扩展，帮助你管理这些场景。

### 将操作标记为实验版、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: 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/managing-api-operations.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.