¿Qué es Swagger? OpenAPI Specification, Herramientas, Ejemplos

¿Qué es Swagger?

Swagger es un ecosistema de herramientas open-source construidas alrededor de la OpenAPI Specification (OAS) para diseñar, documentar y consumir APIs REST. Originalmente desarrollado por SmartBear, la spec fue donada a la Linux Foundation en 2016 y rebranded como OpenAPI — pero el nombre Swagger se mantuvo para el tooling.

La OpenAPI Specification (actualmente 3.1) es un documento YAML o JSON que describe una API REST: endpoints, parámetros, esquemas request/response, autenticación, ejemplos. Las herramientas luego generan documentación, SDKs cliente, server stubs, mock servers y tests desde esta spec.

Swagger vs OpenAPI: ¿cuál es la diferencia?

Anatomía de una spec OpenAPI

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.petstore.example.com/v1
paths:
  /pets:
    get:
      summary: List all pets

Herramientas ecosistema Swagger

¿Por qué usar Swagger / OpenAPI?

• Single source of truth.
• APIs design-first.
• SDKs cliente auto-generados.
• Docs interactivas.
• Mock servers.
• Contract testing.
• Formato estandarizado.
• Code-first o design-first.

OpenAPI 3.0 vs 3.1: ¿qué cambió?

Workflows OpenAPI comunes

Design-first (recomendado)

1. Escribir spec OpenAPI colaborativamente.
2. Revisar con stakeholders.
3. Generar server stubs + SDKs cliente.
4. Implementar lógica negocio en stubs.
5. Usar spec para contract tests en CI.

Code-first

1. Anotar código con decorators framework-specific.
2. Framework auto-genera spec OpenAPI.
3. Spec servida en /openapi.json.
4. Swagger UI renderiza docs interactivas.

Pitfalls y mejores prácticas

• Spec se desvía de realidad.
• Ejemplos faltantes.
• Naming inconsistente.
• Nesting muy profundo.
• Auth mal documentada.
• Versioning ignorado.

FAQ: Swagger / OpenAPI

¿Es Swagger gratis?

Las herramientas open-source son gratis. Swagger Hub tiene tier gratis y planes pagos.

¿Debería usar Swagger o Postman?

Propósitos diferentes. Swagger/OpenAPI es el formato spec; Postman es para testing/exploring.

¿Debería usar design-first o code-first?

Design-first para APIs estables, públicas. Code-first para APIs internas/iterando rápido.

¿Qué reemplaza Swagger Codegen?

OpenAPI Generator — un fork comunitario con desarrollo más activo.

¿Puedo usar Swagger para GraphQL o gRPC?

No — OpenAPI es REST-específico.

¿Cómo versionar mi API?

URL versioning (/v1/users) o header versioning.

Load-testea tu API documentada con Swagger con LoadFocus

Si tienes una spec OpenAPI y quieres load-testear la implementación, LoadFocus corre scripts JMeter y k6 contra tu API real desde 25+ regiones con hasta 12.500 VUs. Regístrate en loadfocus.com/signup.