> 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 をドキュメント化する

ページに OpenAPI 仕様を追加し、インタラクティブなブロックを使って訪問者がページ上でそのままエンドポイントをテストできるようにしましょう。

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

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) — webhooks など、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 ブロックは、「test it」機能もサポートしており、訪問者はエディタで入力したデータやパラメータを使って API メソッドを試すことができます。

これは [Scalar](https://scalar.com/)によって動作するため、APIメソッドの実際の動作を確認するためにドキュメントを離れる必要はありません。上記の例をご覧ください。

#### FAQ

<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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
