SwaggerとOpenAPI仕様ファイルの基本構造

Swaggerは、REST APIをドキュメント化するための仕様です。これにより、REST Webサービスを記述するための形式を指定します。

REST V2コネクタは、Swagger仕様2.0とOpenAPI 3.0.xをサポートしており、Webサービスアプリケーションと対話します。Rest V2接続を設定する場合は、［Swaggerファイルパス］プロパティでSwaggerまたはOpenAPIファイルのパスを指定できます。

SwaggerまたはOpenAPI仕様ファイルには、次のような詳細が含まれています。

Server

サーバーURLの配列は、OpenAPI仕様のserversセクションで指定できます。

次の例は、サーバーがOpenAPI仕様ファイルでどのように定義されているかを示しています。

{
"servers": [
{
"url": "https://development.gigantic-server.com/v1",
"description": "Development server"
},
{
"url": "https://staging.gigantic-server.com/v1",
"description": "Staging server"
},
{
"url": "https://api.gigantic-server.com/v1",
"description": "Production server"
}
]
}

サーバーは、パスレベルでグローバルに定義するか、特定の操作に対して定義することができます。ただし、Rest V2コネクタは、仕様ファイルにリストされている最初のサーバーを優先してRESTエンドポイントに接続します。

または、Rest V2接続の作成時にサーバーURLを指定する場合は、ホストURLをhosturl:schemes://hostの形式で［詳細フィールド］プロパティに追加することができます

接続プロパティで指定されているサーバーは、仕様ファイルで指定されているサーバーよりも優先されます。

Rest V2接続の作成の詳細については、「Rest V2接続プロパティ」を参照してください。

Swagger仕様では、hostキーワードを使用してサーバーURLを定義できます。Swagger仕様ファイルに複数のサーバーを定義することはできません。

次の例は、サーバーがSwagger仕様ファイルでどのように定義されているかを示しています。

{
"host": "petstore.swagger.io",
"basePath": "/v2",
"schemes": [
"https"
]
}

パラメータ

OpenAPI仕様では、パスレベルおよび特定の操作のパラメータを定義することができます。パスレベルのパラメータは、パスの下で定義されたすべての操作に適用されます。操作レベルのパラメータは、その操作が定義されている作業にのみ適用されます。

パスレベルと操作レベルで同じパラメータが定義されている場合は、操作レベルのパラメータが優先されます。

次のようなパラメータタイプを定義することができます。

次の例は、パラメータがOpenAPI仕様ファイルでどのように定義されているかを示しています。

"paths": {
"/pet": {
"put": {
"tags": [
"pet"
],
"summary": "Update an existing pet",
"description": "Update an existing pet by Id",
"operationId": "updatePet",
"parameters": [
{
"name": "status",
"in": "query",
"description": "Status values that need to be considered for filter",
"required": false,
"explode": true,
"schema": {
"type": "string",
"default": "available",
}
}
]

注: OpenAPI仕様のパラメータセクションにスキーマタイプが含まれていることを確認してください。

Swagger仕様ファイルでは、各操作のパラメータを定義することができます。

次の例は、パラメータがSwagger仕様ファイルでどのように定義されているかを示しています。

"parameters": [
{
"in": "body",
"name": "user",
"description": "The user to create.",
"schema": {
"$ref": "#/definitions/User"
}
}
]

要求本文

要求本文により、エンドポイント要求本文の構造を定義します。

OpenAPI仕様ファイルでは、RESTエンドポイントに接続するためのパラメータとrequestBodyを定義することができます。

次の例は、requestBodyがOpenAPI仕様ファイルでどのように定義されているかを示しています。

"operationId": "addPet",
"requestBody": {
"description": "Create a new pet in the store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}

Swagger仕様ファイルでは、RESTエンドポイントに要求を送信するためのパラメータセクションを定義することができます。

次の例は、要求本文がSwagger仕様ファイルでどのように定義されているかを示しています。

{
"paths": {
"/users": {
"post": {
"summary": "Creates a new user.",
"consumes": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "user",
"description": "The user to create.",
"schema": {
"$ref": "#/definitions/User"
}
}
]

応答本文

応答本文により、エンドポイントの応答フィールドを定義します。Rest V2コネクタは、HTTP状態コード200の正常な応答のみをサポートします。ステータスコード200以外のすべての応答について、フィールドマッピングにはResponse_Portという名前の静的フィールドが表示されます。

次の例は、OpenAPI仕様ファイルの応答本文セクションを示しています。

"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/xml": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
}

次の例は、Swagger仕様ファイルの応答本文セクションを示しています。

"responses": {
"200": {
"description": "A User object",
"schema": {
"$ref": "#/definitions/User"
}
}
}