> 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/create-content/openapi.md).

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

OpenAPI スペックをページに追加し、インタラクティブブロックを使ってユーザーがその場でエンドポイントをテストできるようにします。

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

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

GitBook にインポートすると、これらのドキュメントはインタラクティブでテスト可能な API ブロックに変換され、ファイルとして提供された仕様でも URL から読み込まれた仕様でも、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 メソッドをテストできます。

AI 搭載 [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/create-content/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.