# 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`&#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 %}