Swagger
Swagger is an open specification for defining REST APIs.
A Swagger document is the REST API equivalent of a WSDL document for a SOAP-based web service.
The Swagger document specifies the list of resources that are available in the REST API and the operations that can be called on those resources. The Swagger document also specifies the list of parameters to an operation, including the name and type of the parameters, whether the parameters are required or optional, and information about acceptable values for those parameters. Additionally, the Swagger document can include JSON Schema that describes the structure of the request body that is sent to an operation in a REST API, and the JSON schema describes the structure of any response bodies that are returned from an operation.
Swagger documents must be in either JSON format with a .json file extension, or YAML format with a .yaml or .yml file extension.
IBM® Integration Bus supports version 2.0 of the Swagger specification. For information about Swagger, see Swagger. For information about version 2.0 of the Swagger specification, see Swagger RESTful API Documentation Specification Version 2.0.
- Swagger Editor
- Assists you in building a Swagger document from a web browser by providing a side-by-side view of the Swagger document and the resulting REST API definitions. After you build your Swagger document, you can download it to use with IBM Integration Bus. For more information, see GitHub: Swagger Editor.
- Swagger UI
- Allows you to visualize and test a REST API that is defined with Swagger from any web browser. The built-in testing functions allow you to specify the inputs to an operation that is defined in that REST API, call that operation from the web browser, and inspect the results of calling that operation. For more information, see GitHub: Swagger UI.
- Swagger Codegen
- Generates a Software Development Kit (SDK) in various languages, including Java™, Objective-C, PHP, and Python, from a Swagger document for a REST API. The resulting SDK can be used to embed calls to the operations in that REST API into a software program that was written in one of the supported languages, without having to handle the underlying HTTP transport. For more information, see GitHub: Swagger Code Generator.
Most of the Swagger tools accept a Swagger document as a URL that points to a Swagger document that is hosted on an HTTP server. When you deploy REST APIs to IBM Integration Bus, the Swagger document is published over HTTP for you to use with the Swagger tools. The scheme, host, and port number details of the Swagger document are automatically updated to match the details of the running REST API, so that Swagger can be used to call the running REST API.
IBM Integration Bus places some restrictions on Swagger documents, see Restrictions on Swagger documents.
To see an example of a Swagger document, see Swagger petstore.
{
"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"
]
}
}
}
}