swagger

Concepto general

  • Swagger es un conjunto de herramientas y especificaciones para diseñar, documentar, probar y consumir api.
  • Se basa en la especificación OpenAPI (OAS), estándar abierto para describir APIs REST.
  • Permite que humanos y máquinas entiendan la API sin acceder al código fuente.
  • Facilita la comunicación entre backend, frontend, QA, DevOps y clientes externos.

Relación con OpenAPI

  • Swagger fue el origen histórico de OpenAPI.
  • Actualmente:
    • OpenAPI = especificación
    • Swagger = ecosistema de herramientas que implementan OpenAPI
  • Un archivo OpenAPI (openapi.yaml o openapi.json) es el núcleo de Swagger.

Objetivos principales

  • Documentar APIs de forma estandarizada
  • Validar contratos API (contract-first / design-first)
  • Probar endpoints sin cliente personalizado
  • Generar clientes, SDKs y servidores automáticamente
  • Reducir errores de integración

Componentes del ecosistema Swagger

  • Swagger Editor
  • Swagger UI
  • Swagger Hub
  • Swagger AI
  • Swagger Codegen / OpenAPI Generator

Swagger Editor

Swagger UI

  • Interfaz gráfica para visualizar y probar APIs
  • Genera documentación interactiva desde OpenAPI
  • Permite ejecutar llamadas reales (Try it out)
  • Muy usada en entornos de desarrollo y QA
  • Frecuentemente integrada en frameworks backend

Swagger Hub

  • Plataforma colaborativa para equipos
  • Funcionalidades:
    • Versionado de APIs
    • Revisión y comentarios
    • Gestión de múltiples APIs
    • Integración con CI/CD
  • Enfoque enterprise y equipos grandes

Swagger AI

  • Uso de IA para:
    • Generar documentación desde definiciones parciales
    • Detectar inconsistencias
    • Sugerir mejoras en contratos
  • Orientado a acelerar diseño y mantenimiento de APIs

Documentación de api

  • Swagger permite documentar:
    • Endpoints
    • Métodos HTTP
    • Parámetros
    • Respuestas
    • Errores
    • Autenticación
  • La documentación es:
    • Viva (ligada al contrato)
    • Ejecutable (probable desde UI)
    • Compartible

Parámetros en Swagger

  • Swagger define explícitamente dónde viaja cada parámetro

Query parameters

  • Se envían en la URL
  • Usados para:
    • Filtros
    • Paginación
    • Búsquedas
  • Ejemplo:
    • /users?active=true&page=2

Path parameters

  • Parte obligatoria de la ruta
  • Identifican recursos
  • Ejemplo:
    • /users/{id}

Header parameters

  • Se envían en cabeceras HTTP
  • Usados para:
    • Autenticación
    • Versionado
    • Metadata
  • Ejemplo:
    • Authorization: Bearer token
  • Definidos explícitamente en OpenAPI
  • Usados para:
    • Sesiones
    • Preferencias
  • Menos comunes en APIs modernas REST

Autenticación y seguridad

  • Swagger soporta múltiples esquemas:
    • API Key
    • HTTP Basic
    • Bearer Token (JWT)
    • OAuth 2.0
    • OpenID Connect
  • La seguridad se define:
    • Globalmente
    • Por endpoint

Casos de uso comunes

  • Diseño contract-first de APIs
  • Documentación pública para desarrolladores
  • Testing manual de endpoints
  • Onboarding rápido de nuevos equipos
  • Validación de breaking changes
  • Generación automática de clientes

Integración con frameworks backend

  • Java: Spring Boot (springdoc-openapi, swagger-core)
  • Node.js: Express, NestJS
  • Python: FastAPI, Flask
  • .NET: ASP.NET Core
  • Muchas integraciones generan OpenAPI automáticamente desde anotaciones

Generación de código

  • A partir de OpenAPI se puede generar:
    • Clientes (JS, Java, Python, etc.)
    • Servidores base
    • SDKs
  • Reduce código repetitivo
  • Asegura consistencia con el contrato

Buenas prácticas

  • Usar design-first cuando sea posible
  • Versionar la API explícitamente
  • Documentar errores y códigos HTTP
  • Mantener ejemplos reales
  • No mezclar lógica de negocio con documentación manual
  • Validar el contrato en CI/CD

Recursos oficiales

Swagger – Conceptos avanzados y temas complementarios

Enfoques de diseño de APIs

  • Design-first
    • La especificación OpenAPI se escribe antes del código
    • La API se implementa siguiendo el contrato
    • Ideal para equipos grandes y APIs públicas
  • Code-first
    • El código genera automáticamente la especificación
    • Más rápido para prototipos
    • Riesgo de documentación incompleta o acoplada al framework
  • Contract-driven
    • El contrato OpenAPI es la fuente de verdad
    • Se valida en CI/CD
    • Backend y frontend dependen del mismo contrato

Versionado de APIs en Swagger

  • Estrategias comunes:
    • Versionado en URL (/v1/users)
    • Versionado en header (Accept: application/vnd.api.v1+json)
  • Swagger permite:
    • Mantener múltiples versiones del mismo contrato
    • Comparar cambios entre versiones
  • Importante documentar:
    • Cambios breaking
    • Deprecaciones

Reutilización con components

  • OpenAPI permite definir elementos reutilizables
  • Tipos comunes:
    • schemas
    • parameters
    • responses
    • requestBodies
    • headers
  • Ventajas:
    • Menos duplicación
    • Mayor consistencia
    • Mantenimiento más sencillo

Modelado de datos avanzado

  • Soporte para:
    • Tipos primitivos
    • Objetos anidados
    • Arrays
    • Enumeraciones
  • Composición de esquemas:
    • oneOf
    • anyOf
    • allOf
  • Útil para:
    • Polimorfismo
    • Herencia de modelos
    • Respuestas variables según contexto

Manejo de errores

  • Documentación explícita de:
    • Códigos HTTP (400, 401, 403, 404, 500)
    • Estructura de errores
  • Buenas prácticas:
    • Definir un esquema de error común
    • Incluir mensajes claros
    • Añadir ejemplos de errores frecuentes

Ejemplos y mock de APIs

  • OpenAPI permite definir:
    • Ejemplos por campo
    • Ejemplos completos de request/response
  • Casos de uso:
    • Mock servers
    • Frontend sin backend real
    • Pruebas tempranas de integración
  • Swagger Hub permite levantar mocks automáticos

Testing y validación

  • Validación de:
    • Especificación OpenAPI
    • Requests y responses contra el contrato
  • Integración con:
    • Tests automáticos
    • Pipelines CI/CD
  • Previene:
    • Cambios incompatibles
    • Respuestas fuera de contrato

Automatización en CI/CD

  • Usos habituales:
    • Validar OpenAPI en cada commit
    • Comparar contratos entre versiones
    • Bloquear despliegues con breaking changes
  • Swagger/OpenAPI como artefacto versionado

Documentación pública vs privada

  • Swagger permite:
    • Ocultar endpoints internos
    • Documentar solo lo expuesto al cliente
  • Estrategias:
    • Múltiples archivos OpenAPI
    • Filtrado por tags
  • Útil para:
    • APIs internas
    • APIs partner
    • APIs públicas

Tags y organización

  • Uso de tags para:
    • Agrupar endpoints
    • Mejorar navegación en Swagger UI
  • Buenas prácticas:
    • Tags alineados con dominios de negocio
    • Evitar tags genéricos (default, misc)

Internacionalización de documentación

  • Descripciones en:
    • Inglés
    • Idiomas locales
  • Estrategias:
    • Múltiples contratos
    • Campos descriptivos claros y concisos
  • Importante para APIs globales

Limitaciones de Swagger

  • No describe lógica de negocio compleja
  • No reemplaza:
    • Diagramas de arquitectura
    • Documentación funcional
  • Puede crecer demasiado si no se estructura bien

Swagger en APIs no REST

  • Uso limitado fuera de REST
  • Posible adaptación para:
    • APIs HTTP no RESTful
  • Alternativas más adecuadas:
    • AsyncAPI para eventos
    • GraphQL SDL para GraphQL

Alternativas y estándares relacionados

  • OpenAPI (base de Swagger)
  • AsyncAPI
    • Documentación de sistemas event-driven
  • GraphQL
    • Autodescriptivo, pero distinto paradigma
  • gRPC + Protobuf
    • Contrato fuerte, binario
    • Swagger no es nativo aquí

Evolución y futuro

  • Mayor uso de:
    • Contract testing
    • Mocking automático
    • IA para generación y mantenimiento
  • Swagger/OpenAPI como:
    • Pilar del API lifecycle
    • Fuente única de verdad para integraciones

Swagger – Casos de uso con ejemplos de código

Caso de uso: Diseño contract-first de una api

  • Se define el contrato OpenAPI antes de escribir código
  • Backend y frontend trabajan en paralelo
  • El contrato es la fuente de verdad

Ejemplo: Definición OpenAPI mínima

openapi.yaml

openapi: 3.0.3
info:
	title: User API
	version: 1.0.0
paths:
	/users:
		get:
			summary: Obtener usuarios
			responses:
				"200":
					description: Lista de usuarios

`

Caso de uso: Documentación interactiva con Swagger UI

  • Exponer documentación navegable
  • Permitir pruebas manuales de endpoints
  • Reducir dependencias de herramientas externas

Ejemplo: Integrar Swagger UI en Spring Boot

Dependencia Maven

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
	<version>2.5.0</version>
</dependency>

Acceso a Swagger UI

http://localhost:8080/swagger-ui.html

Caso de uso: Documentar parámetros (query, path, header)

  • Evitar ambigüedades en el consumo de la API
  • Permitir validación automática de inputs

Ejemplo: Parámetros en OpenAPI

parameters.yaml

paths:
	/users/{id}:
		get:
			parameters:
				- name: id
					in: path
					required: true
					schema:
						type: integer
				- name: verbose
					in: query
					schema:
						type: boolean
				- name: Authorization
					in: header
					required: true
					schema:
						type: string
			responses:
				"200":
					description: Usuario encontrado

Caso de uso: Documentar request y response bodies

  • Definir claramente estructuras de entrada y salida
  • Facilitar validaciones y generación de clientes

Ejemplo: Request y Response

schemas.yaml

components:
	schemas:
		User:
			type: object
			properties:
				id:
					type: integer
				name:
					type: string
				email:
					type: string

Uso del schema

paths:
	/users:
		post:
			requestBody:
				required: true
				content:
					application/json:
						schema:
							$ref: "#/components/schemas/User"
			responses:
				"201":
					description: Usuario creado

Caso de uso: Autenticación con Bearer Token (JWT)

  • Definir seguridad una sola vez
  • Aplicarla globalmente o por endpoint

Ejemplo: Seguridad en OpenAPI

security.yaml

components:
	securitySchemes:
		BearerAuth:
			type: http
			scheme: bearer
			bearerFormat: JWT

security:
	- BearerAuth: []

Caso de uso: Manejo y documentación de errores

  • Respuestas de error consistentes
  • Mejor experiencia para consumidores

Ejemplo: Respuesta de error estándar

errors.yaml

components:
	schemas:
		ErrorResponse:
			type: object
			properties:
				code:
					type: string
				message:
					type: string

Uso en responses

responses:
	"400":
		description: Petición inválida
		content:
			application/json:
				schema:
					$ref: "#/components/schemas/ErrorResponse"

Caso de uso: Generación automática de clientes

  • Reducir código manual
  • Asegurar compatibilidad con el contrato

Ejemplo: Generar cliente JavaScript

CLI

openapi-generator-cli generate \
	-i openapi.yaml \
	-g javascript \
	-o client-js

Caso de uso: Mock de APIs para frontend

  • Desarrollar frontend sin backend real
  • Probar flujos completos desde Swagger

Ejemplo: Definir ejemplos para mock

mock.yaml

paths:
	/users:
		get:
			responses:
				"200":
					description: Lista mockeada
					content:
						application/json:
							example:
								- id: 1
									name: Alice
								- id: 2
									name: Bob

Caso de uso: Validación en CI/CD

  • Prevenir cambios incompatibles
  • Garantizar estabilidad del contrato

Ejemplo: Validación de OpenAPI

Script de validación

swagger-cli validate openapi.yaml

Caso de uso: Organización por tags

  • Mejor navegación en Swagger UI
  • APIs grandes más legibles

Ejemplo: Uso de tags

tags.yaml

paths:
	/users:
		get:
			tags:
				- Users
			summary: Listar usuarios

Caso de uso: Comparación y control de breaking changes

  • Detectar cambios incompatibles
  • Controlar evolución de la API

Ejemplo: Comparar contratos

Diff de OpenAPI

openapi-diff old.yaml new.yaml

Caso de uso: Documentación pública para terceros

  • Publicar contrato como referencia oficial
  • Reducir soporte y consultas repetidas

Ejemplo: Publicación

  • Archivo openapi.yaml como artefacto versionado
  • Swagger UI desplegado en entorno público