OpenAPI のフィールド

OpenAPI (以前は Swagger と呼ばれていました) は、API (アプリケーションプログラミングインターフェイス) を構築するための仕様です。 RESTful API を定義、文書化、および使用する標準的な方法を提供します。 OpenAPI 仕様は YAML または JSON 形式で記述されており、API のさまざまな側面を定義するために使用される多数のフィールドが含まれています。

OpenAPI で最も一般的に使用されるフィールドの一部を次に示します。

openapi: 使用されている OpenAPI 仕様のバージョンを指定します。
info: タイトル、説明、バージョン、連絡先の詳細など、API に関する情報が含まれています。
servers: API がホストされているサーバーを指定します。
paths: API のエンドポイント (URL) と、それらにアクセスするために使用できる HTTP メソッド (GET、POST、PUT、DELETE など) を定義します。
components: スキーマ、セキュリティスキーム、応答など、API の再利用可能な要素が含まれています。
security: API が使用するセキュリティスキームを指定します。
tags: 操作とエンドポイントをグループ化および整理するためのメタデータを提供します。
externalDocs: API に関連する外部ドキュメントへのリンクが含まれています。

これらは、OpenAPI 仕様で使用できるフィールドのほんの一例です。フィールドの完全なリストは、公式の OpenAPI 仕様ドキュメントに記載されています。

Apigit は、これらのフィールドへの入力にどのように貢献していますか?

OpenAPI 仕様のすべてのフィールドが厳密に必須というわけではありませんが、仕様が有効で完全であることを保証するために含める必要がある特定のフィールドがあります。以下は、OpenAPI 仕様の必須フィールドの一部です。

openapi: 使用されている OpenAPI 仕様のバージョンを指定します。このフィールドは必須であり、仕様のルートレベルに含める必要があります。
info: タイトル、説明、バージョン、連絡先の詳細など、API に関する情報が含まれています。このフィールドは必須であり、仕様のルートレベルにも含まれている必要があります。
paths: API のエンドポイント (URL) と、それらにアクセスするために使用できる HTTP メソッド (GET、POST、PUT、DELETE など) を定義します。このフィールドも必須であり、仕様のルートレベルに含める必要があります。
servers: API がホストされているサーバーを指定します。このフィールドは厳密には必須ではありませんが、API をホストするサーバーに関する情報を提供するために含めることをお勧めします。
components: スキーマ、セキュリティスキーム、応答など、API の再利用可能な要素が含まれています。このフィールドは厳密には必須ではありませんが、仕様の編成と再利用を改善するために含めることをお勧めします。

これらは、OpenAPI 仕様が有効で完全であることを保証するために、OpenAPI 仕様に含める必要がある必須フィールドです。などの他の分野security、tags、とexternalDocs API の必要性と仕様に必要な詳細レベルに応じて、これらを含めることもできます。

Apigit ダッシュボードに API 仕様を追加するには、左上隅にある「+」記号をクリックします。「test/test.json」などのパス名と、「タイトル」や「バージョン」などのその他の関連情報を入力します。空のファイルは、これらすべての必須フィールドに入力するのに役立ちます。

空のスペックファイルを作成する

次に、json コードは次のようになります。

{
  "openapi": "3.0.3",
  "info": {
    "title": "titlet",
    "description": "just a test",
    "termsOfService": "",
    "contact": {
      "email": ""
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0"
  },
  "externalDocs": {
    "description": "Find out more about spec",
    "url": ""
  },
  "servers": [],
  "tags": [
    {
      "name": "Default",
      "description": ""
    }
  ],
  "paths": {},
  "components": {
    "schemas": {},
    "securitySchemes": {}
  }
}

Apigit はどのように支援しますか?

Apigit がフォーム形式のフィールドへの入力をどのように支援するかを説明するために、いくつかの例を示します。追加Field parameter のForm

次に、json コードは次のようになります。

"components": {
    "schemas": {},
    "securitySchemes": {},
    "parameters": {
      "petId": {
        "in": "path",
        "required": true,
        "description": "",
        "schema": {
          "type": "string"
        },
        "name": "PetId"
      }
    }
  }

追加Field path のForm

次に、json コードは次のようになります。

"paths": {
    "/getPet/{petId}": {
      "get": {
        "description": "",
        "operationId": "",
        "tags": [],
        "parameters": [],
        "requestBody": {},
        "responses": {
          "511": {}
        }
      },
      "parameters": [
        {
          "$ref": "#/components/parameters/petId"
        }
      ]
    }
  },