> 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/ja-gitbook-documentation/kontentsuwosuru/openapi.md).

# API をドキュメント化する

REST API のドキュメントを手作業で作成するのは、時間のかかる作業です。幸い、GitBook では API の構造と機能を詳しく示す OpenAPI ドキュメントをインポートできるため、この作業を効率化できます。

OpenAPI Specification（OAS）は、開発者が REST API を文書化するために使用するフレームワークです。JSON または YAML で記述され、すべてのエンドポイント、パラメータ、スキーマ、認証方式を定義します。

GitBook にインポートすると、これらのドキュメントは、仕様がファイルとして提供されている場合でも URL から読み込まれている場合でも、API のメソッドを視覚的に表す、インタラクティブでテスト可能な API ブロックに変換されます。

### OpenAPI の互換性

GitBook は、次の仕様バージョンのインポートとレンダリングをサポートしています：

* [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) — 対応しています。
* [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) — 対応しています。
* [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md) — 対応しています。OpenAPI 3.1 のみの機能も含みます。たとえば `webhooks`.

{% openapi src="<https://petstore3.swagger.io/api/v3/openapi.json>" path="/pet" method="post" %}
<https://petstore3.swagger.io/api/v3/openapi.json>
{% endopenapi %}

### 試してみる（Scalar 搭載）

GitBook の OpenAPI ブロックは「試してみる」機能にも対応しており、エディタで入力したデータやパラメータを使って、ユーザーが API メソッドをテストできます。

提供： [Scalar](https://scalar.com/)、ドキュメントから離れることなく API メソッドの動作を確認できます。上の例をご覧ください。

#### よくある質問

<details>

<summary>なぜ仕様が読み込まれないのですか？</summary>

{% hint style="info" %}
**注：** この情報は次にのみ適用されます **URL で追加された仕様**.
{% endhint %}

仕様を URL 経由で追加した場合、API は [クロスオリジンを許可する必要があります](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin) ドキュメントサイトからの GET リクエストを許可しなければなりません。API の CORS 設定では、ドキュメントがホストされている正確なオリジンを許可してください（例： `https://your-site.gitbook.io` または `https://docs.example.com`）。\
\
エンドポイントが公開されていて認証情報を使わない場合は、次の値を返すこともできます： `Access-Control-Allow-Origin: *`\ <br>

</details>


---

# 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/ja-gitbook-documentation/kontentsuwosuru/openapi.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.