Swagger
Swagger は、REST API を定義するためのオープン仕様です。
Swagger 文書は、SOAP ベースの Web サービスの WSDL 文書に相当する REST API 文書です。
Swagger 文書には、REST API で使用可能なリソースのリストと、それらのリソースに対して呼び出すことができる操作が指定されています。 Swagger 文書には、操作に対するパラメーターのリストも指定されます。これには、パラメーターの名前とタイプ、パラメーターが必須かオプションか、およびそれらのパラメーターの許容値に関する情報が含まれます。 さらに、 Swagger 文書には、REST API で操作に送信される要求本体の構造を記述する JSON スキーマを含めることができます。JSON スキーマは、操作から返される応答本体の構造を記述します。
Swagger 文書は、ファイル拡張子が .json の JSON 形式か、ファイル拡張子が .yaml または .yml の YAML 形式でなければなりません。
IBM® Integration Bus は、 Swagger 仕様のバージョン 2.0 をサポートします。 Swaggerについては、 Swaggerを参照してください。 Swagger 仕様のバージョン 2.0 については、 Swagger RESTful API Documentation Specification Version 2.0を参照してください。
- Swagger エディター
- Swagger 文書と結果の REST API 定義の横並びビューを提供することにより、Web ブラウザーから Swagger 文書を作成するのを支援します。 Swagger 文書を作成した後、それをダウンロードして IBM Integration Busで使用できます。 詳細については、 GitHub: Swagger エディター。
- Swagger UI
- 任意の Web ブラウザーから、 Swagger で定義された REST API を視覚化してテストできます。 組み込みのテスト機能により、その REST API に定義されている操作への入力を指定し、Web ブラウザーからその操作を呼び出して、操作呼び出しの結果を検査できます。 詳細については、 GitHub:スワッガーUI。
- 「Swagger」 「Codegen」
- REST API 用の Swagger 文書から、Java™、Objective-C、PHP、および Pythonなど、さまざまな言語の Software Development Kit (SDK) を生成します。 生成された SDK を使用することで、その REST API 内にある操作の呼び出しを、サポートされている言語のいずれかで書かれたソフトウェア・プログラムに組み込むことができます。基礎となる HTTP トランスポートの処理は必要ありません。 詳細については、 GitHub: Swagger コードジェネレーター。
ほとんどの Swagger ツールは、HTTP サーバーでホストされている Swagger 文書を指す URL として Swagger 文書を受け入れます。 REST API を IBM Integration Busにデプロイすると、 Swagger 文書が HTTP を介して公開され、 Swagger ツールで使用できるようになります。 Swagger 文書のスキーム、ホスト、およびポート番号の詳細は、実行中の REST API の詳細と一致するように自動的に更新されるため、 Swagger を使用して実行中の REST API を呼び出すことができます。
IBM Integration Bus では、 Swagger 文書にいくつかの制約事項があります。 Swagger 文書に関する制約事項を参照してください。
Swagger 文書の例については、 Swagger ペットストアを参照してください。
{
"swagger": "2.0",
"basePath": "/customerdb/v1",
"info": {
"title": "Customer Database",
"description": "This is the customer database sample Swagger document included with IBM Integration Bus.",
"version": "1.0.0"
},
"definitions": {
"Customer": {
"properties": {
"id": {
"type": "integer"
},
"firstname": {
"type": "string"
},
"lastname": {
"type": "string"
},
"address": {
"type": "string"
}
},
"required": [
"firstname",
"lastname",
"address"
]
}
},
"tags": [
{
"name": "customers",
"description": "Operations on customers in the customer database"
}
],
"paths": {
"/customers": {
"get": {
"operationId": "getCustomers",
"summary": "Get all customers from the database",
"parameters": [
{
"name": "max",
"in": "query",
"description": "Maximum number of customers to get from the database",
"required": false,
"type": "integer"
}
],
"responses": {
"200": {
"description": "An array of customers from the database",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Customer"
}
}
}
},
"tags": [
"customers"
]
},
"post": {
"operationId": "addCustomer",
"summary": "Add a customer to the database",
"parameters": [
{
"name": "body",
"in": "body",
"description": "The customer to add to the database",
"required": true,
"schema": {
"$ref": "#/definitions/Customer"
}
}
],
"responses": {
"200": {
"description": "If the customer was successfully added to the database"
}
},
"tags": [
"customers"
]
}
},
"/customers/{customerId}": {
"get": {
"operationId": "getCustomer",
"summary": "Get a specified customer from the database",
"parameters": [
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer to get from the database",
"required": true,
"type": "integer"
}
],
"responses": {
"200": {
"description": "The specified customer from the database",
"schema": {
"$ref": "#/definitions/Customer"
}
}
},
"tags": [
"customers"
]
},
"delete": {
"operationId": "deleteCustomer",
"summary": "Delete a specified customer from the database",
"parameters": [
{
"name": "customerId",
"in": "path",
"description": "The ID of the customer to delete from the database",
"required": true,
"type": "integer"
},
{
"name": "Authorization-Key",
"in": "header",
"description": "Provide the authorization key that permits the customer to be deleted from the database",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "If the customer was successfully deleted from the database"
}
},
"tags": [
"customers"
]
}
}
}
}