# 管理 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`&#x20;

<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 %}