SWAGGER: QUÉ ES Y CÓMO DOCUMENTAR APIS

Swagger es un conjunto de herramientas open-source que se utiliza para diseñar, documentar y consumir API REST de forma moderna y profesional. Actualmente, Swagger es la implementación más popular de la especificación OpenAPI. Swagger es la mejor forma de documentar y probar APIs de forma profesional y visual.

Historia breve

  • Originalmente se llamaba Swagger.
  • En 2015 fue donado a la Linux Foundation y se convirtió en el estándar OpenAPI Specification.
  • Hoy en día la gente sigue llamándolo Swagger, aunque técnicamente el estándar se llama OpenAPI.

¿Para qué sirve Swagger?

  • Documentación interactiva de APIs (lo más famoso).
  • Diseñar APIs antes de programarlas-
  • Generar código automáticamente como clientes en Java, Python, JavaScript, C#, etc.-
  • Probar la API directamente desde el navegador-

Componentes principales de Swagger

Herramienta Qué hace Uso más común
Swagger Editor Editor visual para escribir la especificación Diseñar la API
Swagger UI Interfaz bonita e interactiva Documentación para desarrolladores
Swagger Codegen Genera código cliente y servidor Ahorro de tiempo
Swagger Inspector Herramienta para probar APIs Testing

Ventajas de usar Swagger

  • Documentación siempre actualizada ya que se genera desde el código.
  • Facilita el trabajo en equipo (frontend + backend).
  • Reduce malentendidos entre desarrolladores.
  • Muy usado en empresas (es prácticamente un estándar).
  • Soporta autenticación (JWT, OAuth2, API Key, Basic Auth, etc.).

Tecnologías donde se usa Swagger

  • Node.js (Express + swagger-ui-express).
  • Spring Boot (Springdoc o Swagger).
  • .NET (Swashbuckle).
  • Laravel, NestJS, FastAPI, Go, etc.