Tutorial de documentación de API con Swagger para principiantes - 1 - Introducción a la documentación de API con Swagger

¿Qué es Swagger?

El objetivo de Swagger™ es definir un estándar de interfaz independiente del lenguaje para las APIs REST, lo que permite tanto a humanos como a computadoras descubrir y entender las capacidades de un servicio sin necesidad de acceder al código fuente, documentación o inspeccionar el tráfico de red. Cuando una API está correctamente definida mediante Swagger, un consumidor puede entenderla e interactuar con ella con una mínima lógica de implementación. Al igual que las interfaces lo han hecho en la programación de bajo nivel, Swagger elimina las suposiciones al llamar a un servicio.

Técnicamente hablando, Swagger es una especificación formal rodeada de un amplio ecosistema de herramientas, que incluye desde interfaces de usuario front-end, bibliotecas de código de bajo nivel y soluciones comerciales de gestión de APIs.

¿Por dónde empezar?

Si eres proveedor de APIs y quieres usar Swagger para describirlas, hay varias aproximaciones disponibles:

Un enfoque *top-down* donde usarías el Swagger Editor para crear tu definición Swagger y luego emplearías las herramientas integradas Swagger Codegen para generar la implementación del servidor.
Si o