Swagger
Swagger es una especificación abierta para definir las API REST.
Un documento Swagger es el equivalente de la API REST de un documento WSDL para un servicio web basado en SOAP.
El documento Swagger especifica la lista de recursos que están disponibles en la API REST y las operaciones que se pueden llamar en esos recursos. El documento Swagger también especifica la lista de parámetros de una operación, incluido el nombre y el tipo de los parámetros, si los parámetros son necesarios o opcionales, e información sobre los valores aceptables para dichos parámetros. Además, el documento Swagger puede incluir el esquema JSON que describe la estructura del cuerpo de solicitud que se envía a una operación en una API REST, y el esquema JSON describe la estructura de los cuerpos de respuesta que se devuelven de una operación.
Los documentos Swagger deben estar en formato JSON con la extensión de archivo .json o en formato YAML con la extensión de archivo .yaml o .yml.
IBM® Integration Bus da soporte a la versión 2.0 de la especificación Swagger . Para obtener información sobre Swagger, consulte Swagger. Para obtener información sobre la versión 2.0 de la especificación Swagger , consulte Swagger RESTful API Documentation Specification Versión 2.0.
- Swagger Editor
- Le ayuda a crear un documento Swagger desde un navegador web proporcionando una vista de lado a lado del documento Swagger y las definiciones de API REST resultantes. Después de crear el documento Swagger , puede descargarlo para utilizarlo con IBM Integration Bus. Para obtener más información, consulte GitHub: Editor Swagger.
- IU de Swagger
- Permite visualizar y probar una API REST definida con Swagger desde cualquier navegador web. Las funciones de pruebas incorporadas le permiten especificar las entradas de una operación definida en esa API REST, llamar a dicha operación desde el navegador web e inspeccionar los resultados de llamar a dicha operación. Para obtener más información, consulte GitHub: Interfaz de usuario de Swagger.
- Swagger Codegen
- Genera un SDK (Software Development Kit) en varios idiomas, incluidos Java™, Objective-C, PHP y Python, desde un documento Swagger para una API REST. El SDK resultante se puede utilizar para incorporar llamadas a las operaciones en dicha API REST en un programa de software escrito en uno de los idiomas soportados, sin necesidad de manejar el transporte HTTP subyacente. Para obtener más información, consulte GitHub: Generador de código Swagger.
La mayoría de las herramientas de Swagger aceptan un documento Swagger como un URL que apunta a un documento Swagger alojado en un servidor HTTP. Cuando despliega las API REST en IBM Integration Bus, el documento Swagger se publica a través de HTTP para que lo utilice con las herramientas de Swagger . Los detalles de esquema, host y número de puerto del documento Swagger se actualizan automáticamente para que coincidan con los detalles de la API REST en ejecución, de modo que se pueda utilizar Swagger para llamar a la API REST en ejecución.
IBM Integration Bus coloca algunas restricciones en los documentos Swagger , consulte Restricciones a documentos Swagger.
Para ver un ejemplo de un documento Swagger , consulte 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"
]
}
}
}
}