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® App Connect Enterprise supports version 2.0 of the Swagger specification with some restrictions as described in Restrictions on Swagger documents. For more information about Swagger, see Swagger. For more information about version 2.0 of the Swagger specification, see Swagger RESTful API Documentation Specification Version 2.0.

A range of third-party tools are available for you to use with Swagger documents:
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 App Connect Enterprise. 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 App Connect Enterprise, 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 App Connect Enterprise places some restrictions on Swagger documents, see Restrictions on Swagger documents.

To see an example of a Swagger document, see Swagger petstore.

A copy of the following Swagger document, <install root>/server/sample/restapis/swagger.json is included with the product installation.

{
    "swagger": "2.0",
    "basePath": "/customerdb/v1",
    "info": {
        "title": "Customer Database",
        "description": "This is the customer database sample Swagger document included with IBM App Connect Enterprise.",
        "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"
                ]
            }
        }
    }
}