# OpenAPI

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

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

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

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 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 メソッドを実際に試せます。上の例をご覧ください。

#### 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>