Swagger
Swagger é uma especificação aberta para definição de APIs REST.
Um documento Swagger é o equivalente API REST de um documento WSDL para um serviço web baseado em SOAP.
O documento Swagger especifica a lista de recursos que estão disponíveis na API REST e as operações que podem ser chamadas sobre esses recursos. O documento Swagger também especifica a lista de parâmetros a uma operação, incluindo o nome e o tipo dos parâmetros, se os parâmetros são necessários ou opcionais, e informações sobre valores aceitáveis para esses parâmetros. Adicionalmente, o documento Swagger pode incluir JSON Schema que descreve a estrutura do corpo de solicitação que é enviado para uma operação em uma API REST, e o esquema JSON descreve a estrutura de quaisquer corpos de resposta que são retornados de uma operação.
Os documentos swagger devem estar em qualquer formato JSON com uma extensão de arquivo .json ou formato YAML com uma extensão de arquivo .yaml ou .yml.
IBM® Integration Bus suporta version 2.0 da especificação Swagger . Para obter informações sobre Swagger, consulte Swagger. Para obter informações sobre version 2.0 da especificação Swagger , consulte Especificação de Documentação de API RESTful Swagger RESTful Version 2.0.
- Swagger Editor
- Auxilia você na construção de um documento Swagger a partir de um navegador web fornecendo uma visão lado-a-lado do documento Swagger e as definições de REST API resultantes. Depois de construir o seu documento Swagger , você pode fazer o download para usar com IBM Integration Bus. Para mais informações, consulte GitHub: Editor de Swagger.
- Swagger UI
- Permite que você visualize e teste uma API REST que é definida com Swagger a partir de qualquer navegador web. As funções de teste integradas permitem especificar as entradas para uma operação que está definida nessa API REST, chamam essa operação a partir do navegador da Web e examina os resultados da chamada dessa operação. Para mais informações, consulte GitHub: Swagger UI.
- Swagger Codegen
- Gera um Kit de Desenvolvimento de Software (SDK) em vários idiomas, incluindo Java™, Objective-C, PHP e Python, a partir de um documento Swagger para uma API REST. O SDK resultante pode ser utilizado para integrar chamadas das operações nessa API REST em um programa de software que foi gravado em uma das linguagens suportadas, sem precisar manipular o transporte HTTP subjacente. Para mais informações, consulte GitHub: Gerador de Código Swagger.
A maioria das ferramentas Swagger aceita um documento Swagger como uma URL que aponta para um documento Swagger que é hospedado em um servidor HTTP. Ao implantar APIs REST para IBM Integration Bus, o documento Swagger é publicado sobre HTTP para você usar com as ferramentas Swagger . O esquema, o host e os detalhes de número de porta do documento Swagger são atualizados automaticamente para combinar os detalhes da API REST em execução, de modo que Swagger pode ser usado para chamar a API REST em execução.
IBM Integration Bus coloca algumas restrições em documentos Swagger , veja Restrições aos documentos Swagger.
Para ver um exemplo de um documento Swagger , consulte Petstore de 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"
]
}
}
}
}