Términos Swagger y OpenAPI

May 03 2023

Mientras escribía el artículo anterior, que nunca se publica, me di cuenta de que muchos no entienden la diferencia entre los términos Swagger y OpenAPI (OAS). La gente usa ambos términos indistintamente.

Mientras escribía el artículo anterior, que nunca se publica, me di cuenta de que muchos no entienden la diferencia entre los términos Swagger y OpenAPI (OAS) . La gente usa ambos términos indistintamente. No los culpo ya que yo tenía las mismas dudas.

Swagger le permite describir la estructura de sus API para que las máquinas puedan leerlas.
— SwaggerIO

Si intenta buscar en Google Swagger u OpenAPI , en la mayoría de los casos, terminará en SwaggerIO , el sitio web oficial de Swagger. Si me preguntas, el sitio web ha oscurecido el propósito de Swagger desde el primer día. Sin embargo, no intencionalmente. No falta información, simplemente no se presenta de manera clara y concisa.

La especificación OpenAPI (OAS) define una interfaz estándar independiente del idioma para las API RESTful que permite que tanto los humanos como las computadoras descubran y comprendan las capacidades del servicio sin acceso al código fuente, la documentación o a través de la inspección del tráfico de la red.
— SwaggerIO

Hoy en día, hay muchos artículos sobre este tema, por lo que es mucho más fácil darse cuenta de la diferencia, pero aún así es posible encontrar escritos que entremezclan los términos. SwaggerIO está promocionando Swagger como un conjunto de herramientas y OpenAPI como una especificación. Podríamos decir que el Swagger se usa para crear la especificación OpenAPI . Esencialmente, esta declaración no es incorrecta, pero no es toda la verdad.

SwaggerIO mezcla términos Swagger con OpenAPI

Uso de los términos

Por lo general, los desarrolladores usan el término Swagger en, al menos, dos contextos:

describir un conjunto de herramientas para implementar la especificación. Algunas herramientas son Swagger Editor, Swagger UI, Swagger Codegen, etc. Es un ecosistema.
para describir la especificación de la versión 2.*.*

Los desarrolladores usan el término Especificación 3 de OpenAPI principalmente en un solo contexto:

para describir la especificación de la versión 3.*.*. La comunidad se refiere a OAS, OAS3, OpenAPI Spec, OpenAPI 3 Specification, etc. Adoptaron OpenAPI 3 como sucesor de Swagger Specification 2.

Swagger y OpenAPI son amigos cercanos por una razón. La historia es el ingrediente clave aquí.

La empresa SmartBear mantiene Swagger. En noviembre de 2015, The Linux Foundation anunció que estaban creando, junto con SmartBear, Google, Microsoft, Paypal y algunas otras empresas, una nueva organización, OpenAPI Initiative. La tarea principal de la iniciativa era ampliar la especificación Swagger.

Unos meses después, la iniciativa cambió el nombre de Swagger a la especificación OpenAPI. La iniciativa clonó el código en el nuevo repositorio. A partir de ese momento, las personas han utilizado ambos términos en varios contextos.

última palabra

Swagger solía ser un conjunto de herramientas y especificaciones todo en uno. Hoy, Swagger es un conjunto de herramientas. OpenAPI es una especificación. Eso es todo.

Es bueno saber la diferencia. Sin embargo, cualquiera que sea el término que uses, la otra parte te entenderá; al final, eso es lo único que importa.