What is Swagger

¿Qué es Swagger y para qué sirve?

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.

¿Qué es la documentacion de la API?

La documentación de API, como su propio nombre indica, abarca la redacción del contenido informativo sobre el uso de API. La guía se presenta, normalmente, bajo una serie de referencias y tutoriales acompañados de ejemplos que ayudan a los desarrolladores a entender la Interfaz de Programación de Aplicaciones API.

Como utilizar Swagger

Instalacion de Swaggwe

Para instalar swagger en nuestro proyecto de node con express debemos utilizar el siguiente modulo:

$ npm i swagger-ui-express --save

Una vez instalado debemos configurar nuestro proyecto agregando el siguiente codigo para anexar nuestro archivo de swagger:

1...
2const swaggerUI = require('swagger-ui-express');
3const swagggerDocument = require('./swagger.json');
4...

Una vez agregado crearemos una ruta para acceder a la documentacion generada por swagger desde el middleware:

1...
2const options = {
3    explorer: true
4}
5app.use('/docs', swaggerUI.serve, swaggerUI.setup(swaggerDocument, options));
6...

Una vez configurado todo nuestro proyecto para acceder a nuestra documentacion con swagger pasaremos a configurar nuestro archivo swagger.json

Informacion Básica

Esta seccion contiene de las especificaciones de swagger los datos basicos de nuestro proyecto:

1
2{
3    "openapi": "3.0.3",
4    "info": {
5        "title": "REST API Documentation",
6        "description": "example of a REST API Documentation",
7        "version": "1.0.0",
8        "contact": {
9            "name": "John Doe",
10            "email": "john.doe@example.com",
11            "url": "www.johndoe.com"
12        }
13    }
14}
15

Resuldado:

Servidores

1{
2    ...
3    "servers": [
4        {
5            "url": "http://localhost:3000/v1",
6            "description": "Local Server v1"
7        }
8    ],
9    ...
10}
11

Resultado:

Para poder seguir configurando nuestro archivo swagger.json podemos seguir las expecificaciones de la documentacion de OpenAPI en la seccion de "schema"