OpenAPI

OpenAPI仕様をページに追加し、インタラクティブなブロックでユーザーがページ上でエンドポイントをテストできるようにする

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

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

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

GitBookはをサポートしています Swagger 2.0 または OpenAPI 3.0 準拠ファイル。

Add a new pet to the store.

post

Add a new pet to the store.

必須スコープ

このエンドポイントには次のスコープが必要です：

• : modify pets in your account
• : read your pets

認可

petstore_auth

OAuth2implicit必須

Authorization URL:

本文

application/jsonapplication/xmlapplication/x-www-form-urlencoded

idinteger · int64オプションExample: 10

namestring必須Example: doggie

photoUrlsstring[]必須

statusstring · enumオプション

pet status in the store

可能な値:

レスポンス

200

Successful operation

application/jsonapplication/xml

400

Invalid input

422

Validation exception

default

Unexpected error

post

/pet

HTTPcURLJavaScriptPython

POST /api/v3/pet HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "text"
  ],
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "status": "available"
}

application/jsonapplication/xmlapplication/x-www-form-urlencoded

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "text"
  ],
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "status": "available"
}

テストする（Scalar による提供）

GitBook の OpenAPI ブロックは「テストする」機能もサポートしており、エディタから入力されたデータとパラメータを使ってユーザーが API メソッドをテストできるようにします。

提供： Scalar、ドキュメントを離れることなく API メソッドの動作を確認できます。上の例を参照してください。

よくある質問

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

注意： この情報は次にのみ適用されます URL で追加された仕様.

仕様を URL 経由で追加した場合、あなたの API は次を満たす必要があります クロスオリジンを許可する ドキュメントサイトからの GET リクエスト。API の CORS 設定で、ドキュメントがホストされている正確なオリジンを許可してください（例： https://your-site.gitbook.io または https://docs.example.com）。 エンドポイントが公開されており認証情報を使用していない場合は、次も返すことができます: Access-Control-Allow-Origin: *