¿Qué es Swagger?
Swagger es una suite de herramientas para diseñar, construir, documentar y utilizar APIs. Facilita la creación de especificaciones OpenAPI, las cuales definen cómo se estructuran las API. Swagger permite a los desarrolladores y a las organizaciones gestionar el ciclo de vida completo de una API.
Una imagen de ejemplo:
¿Cómo probar Swagger?
Tenemos varias formas de probar Swagger y el uso es igual en todos. Lo que tienen en común es que se usan desde plantillas YAML, que más adelante veremos un ejemplo.
- A traves de su web: Swagger tiene una web llamada editor.swagger.io donde puedes probar las plantillas que crees. Este editor online te permite visualizar y validar tus especificaciones OpenAPI en tiempo real. Simplemente copia y pega tu plantilla YAML en el editor y verás una representación gráfica en la parte derecha.
- Con contenedor Docker: Tenemos la posibilidad de instalarlo con docker-compose que es la opción veremos en el post.
Instalación de Swagger usando Docker-compose
Como ya sabremos, para estas pruebas necesitaremos tener instaldo docker y docker-compose.
La estructura del proyecto lo podemos definir de la siguiente manera:
|-- docker-compose.yml
|-- README.md
|-- swagger.yml
|-- /swagger
|-- ejemplo1.yaml
|-- ejemplo2.yaml
Puedes clonar o descargar la repo desde GitHub en:
https://github.com/Pistatxos/swaggerDocker
También puedes copiar el código de ejemplo.
Ejemplo plantilla básica
version: '3'
services:
swagger-ui:
image: swaggerapi/swagger-ui:latest
container_name: "swagger-ui"
ports:
- "8880:8080"
volumes:
- ./swagger/swagger.yaml:/swagger.yaml
environment:
SWAGGER_JSON: /swagger.yaml
VALIDATOR_URL: "" # Lo añadimos para que no salga el cartel de invalid.Ejemplo plantilla con desplegable para poder usar varios swagger.
version: '3'
services:
swagger-ui:
image: swaggerapi/swagger-ui:latest
container_name: "swagger-ui"
ports:
- "8880:8080"
volumes:
- ./swagger:/usr/share/nginx/html/swagger
environment:
URLS_PRIMARY_NAME: "API Ejemplo 1"
URLS: '[{"name": "API Ejemplo 1", "url": "/swagger/ejemplo1.yaml"}, {"name": "API Ejemplo 2", "url": "/swagger/ejemplo2.yaml"}]'
VALIDATOR_URL: ""Para añadir cualquiera de los dos ejemplos a una red docker existente:
## Dentro del servicio swagger-ui
networks: # En caso de tener una network
- network_que_tengamos
## En caso de tener una network o querer usarlo con nginx para poner contraseña.
networks:
network_que_tengamos:
external: trueAñadiremos dentro de la carpeta swagger las plantillas, por ejemplo: plant1.yaml y plant2.yaml.
Ejemplo de plantilla Swagger
Adjunto la plantilla con varios ejemplos para que sea más fácil a la hora de crear vuestra nueva plantilla.
openapi: 3.0.0
info:
title: API Ejemplo
description: |-
<p align="right">
<img src="https://tomonota.net/wp-content/uploads/2024/08/Logo-Tomonota-Negro-e1723131211126.png" alt="LOGO" />
</p>
Descripción de la api...
Gracias a: [TomoNota](https://tomonota.net)
Tenemos varios ejemplos de uso de la plantilla.
- Para documentar.
- Y presentar.
**Espero os sea de ayuda**
version: 1.0.0
servers:
- url: https://tu.dominio.com
description: Servidor de prueba
tags:
- name: grupo1
description: Consultas a la base de datos.
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
security:
- BearerAuth: []
paths:
/recursoEjemplo:
get:
tags:
- grupo1
summary: Comentario linea método get.
description: Descripción de la consulta get.
responses:
'200':
description: Respuesta correcta.
'400':
description: Datos incorrectos.
'500':
description: Error en el servidor.
post:
tags:
- grupo1
summary: Comentario linea método post
description: Descripción método post.
operationId: consultarRegistros
parameters:
- name: username
in: query
required: true
schema:
type: string
example: "texto ejemplo"
description: Descripción ejemplo.
- name: varios
in: query
required: true
schema:
type: string
enum: [varios1, varios2, varios3]
description: Ejemplo con desplegable.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name_test:
type: string
example: "ejemplo"
name_test2:
type: string
example: "ejemplo2"
security:
- BearerAuth: []
responses:
'200':
description: |
Existen varias posibilidades para esta respuesta:
- Se puede organizar un poco el texto.
- De varias maneras.
- Como en este:
- Ejemplo texto.
'400':
description: Datos incorrectos.
'500':
description: Error en el servidor.
put:
tags:
- grupo1
summary: Comentario linea método put.
description: Descripción método put.
parameters:
- name: username
in: query
required: true
schema:
type: string
example: "texto ejemplo"
description: Descripción ejemplo.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name_test:
type: string
example: "ejemplo"
name_test2:
type: string
example: "ejemplo2"
security:
- BearerAuth: []
responses:
'200':
description: Respuesta correcta.
'400':
description: Datos incorrectos.
'500':
description: Error en el servidor.
delete:
tags:
- grupo1
summary: Comentario linea método delete.
description: Descripción método delete.
parameters:
- name: username
in: query
required: true
schema:
type: string
example: "texto ejemplo"
description: Descripción ejemplo.
security:
- BearerAuth: []
responses:
'200':
description: Respuesta correcta.
'400':
description: Datos incorrectos.
'500':
description: Error en el servidor.Configurando en nginx y opción de añadir autentificación
En el post de Nginx Docker: Enlace – Nginx con Docker tenemos ejemplos para poder establecer una contraseña de acceso. Seguro que te va bien si quieres proteger el acceso, además de poder añadir un SSL y así conectar de manera segura.
Siguiendo los ejemplos del post podrás configurar y probar tus APIs utilizando Swagger y Docker-compose, facilitando la gestión y documentación de tus servicios de manera eficiente, tu trabajo resaltará!
Espero que os sirva de ayuda.
Salu2!
