Cargando...

Documenta tu Api con Swagger

Swagger es uno de los frameworks más populares para documentar API's REST por muchos motivos:

  • Genera una consola interactiva para hacer pruebas de la API
  • Genera un cliente tipo SDK para que se integre en las plataformas de terceros
  • Puede leer los comentarios del código fuente para generar la documentación

Por defecto, Swagger utiliza JSON o YAML para describir la API, lo que permite que se generen los archivos desde cualquier editor de texto.

Por ejemplo, si tenemos una API que permite obtener la lista de productos o un producto en particular, el archivo de esta documentación en Swagger sería similar a esto:

{ "apiVersion": "1.0", "swaggerVersion": "2.1", "basePath": "http://products.api.sincco.com/", "resourcePath": "/products", "produces": [ "application/json" ], "apis": [ { "path": "/products/", "operations": [ { "method": "GET", "summary": "Regresa todos los productos del catalogo", "notes": "Regresa todos los productos del catalogo.", "nickname": "getJobsgetProducts", "type": "products", "parameters": [ { "name": "query", "description": "a text query to search across products", "required": false, "allowMultiple": false, "dataType": "string", "paramType": "query" } ], "produces": [ "application/json" ], "responseMessages": [ { "code": 404, "message": "No Jobs To Return" } ] } ] }, { "path": "/products/{id}", "operations": [ { "method": "GET", "summary": "Regresa un producto desde su ID", "notes": "Regresa el detalle de un producto", "type": "products", "nickname": "getProducts", "produces": [ "application/json" ], "parameters": [ { "name": "id", "description": "ID del producto", "required": false, "allowMultiple": false, "dataType": "integer", "paramType": "path" } ], "responseMessages": [ { "code": 400, "message": "ID invalido (contenido erroneo)" }, { "code": 404, "message": "Producto no encontrado" } ] } ] } ], "models": { "products": { "id": "products", "properties": { "id": { "type": "integer" }, "sku": { "type": "string" }, "descripcion": { "type": "string" } } } } }

Donde definimos las dos rutas (una para todos los productos y otra para un sólo producto) que son parte de la API y los parametros que se reciben en cada una.

La seccion de models especifica la estructura de los datos del producto y que usamos en el atributo type en la definición de los métodos.

En http://swagger.io/ podrás encontrar la documentación completa y ejemplos de implementación que te permitirá documentar tu API de modo fácil y con una apariencia profesional.