¿Qué es Swagger? Swagger y OpenAPI explicados

¿Qué es Swagger?

Swagger es la familia de herramientas de código abierto, sobre todo Swagger UI y Swagger Editor, construida en torno a la OpenAPI Specification, el formato estándar para describir APIs HTTP. Escribes una descripción legible por máquinas de tu API y las herramientas la convierten en documentación interactiva, código de cliente y servidor, servidores simulados y pruebas. "Swagger" fue además el nombre original de la propia especificación.

Swagger y OpenAPI

Los dos nombres causan la mayor parte de la confusión, así que aquí va la separación:

• OpenAPI Specification (OAS) es el formato: un documento JSON o YAML que describe endpoints, parámetros, esquemas de petición y respuesta, y autenticación. La última versión publicada en el momento de escribir esto es la 3.2.1.
• Swagger es el nombre antiguo de la especificación (hasta el cambio de nombre del 1 de enero de 2016) y hoy el nombre de las herramientas de SmartBear en torno a ella. Un "archivo Swagger 2.0" usa la denominación antigua y Swagger UI sigue leyéndolo.
• Swagger UI muestra una descripción OpenAPI como documentación navegable y deja probar cada operación. Lee archivos Swagger 2.0 y OAS 3.x.
• Swagger Editor es un editor para escribir descripciones OpenAPI con vista previa en vivo y validación.

Un poco de historia: Swagger nació en 2011 y se publicó como código abierto en septiembre de ese año. En noviembre de 2015 SmartBear ayudó a crear la OpenAPI Initiative bajo la Linux Foundation, y la especificación pasó a llamarse OpenAPI.

Cómo es una descripción OpenAPI

Solo son obligatorios openapi e info (con title y version), además de al menos uno de paths, components o webhooks. Un ejemplo pequeño que funciona:

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /pets:
    get:
      summary: List pets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string

A partir de este único archivo, las herramientas pueden generar la página de documentación, un cliente tipado, un esqueleto de servidor y un servidor simulado. El formato completo está en la OpenAPI Specification.

Diseño primero o código primero

• Diseño primero: escribes la descripción, la revisas con quienes consumirán la API y luego generas esqueletos y clientes. Los equipos de frontend pueden trabajar contra un simulacro (simulación de APIs) mientras se construye el backend. Encaja con un enfoque API-first.
• Código primero: anotas el código y el framework genera la descripción. Es rápido para empezar, pero la descripción solo es tan precisa como las anotaciones.

Errores comunes

• Dejar que la especificación se aleje de la API real. Una descripción que nadie comprueba se queda obsoleta. Ejecuta pruebas de contrato en CI y contrasta la API en vivo con ella.
• Sin ejemplos. Añade valores example en los esquemas para que la documentación y los simulacros generados sean útiles.
• Errores sin documentar. Describe las respuestas 4xx y 5xx, no solo la 200.
• Esquema de seguridad incorrecto. Si la autenticación está mal descrita, los clientes generados y "Try it out" fallan con 401.
• Tomarlo por herramienta de GraphQL o gRPC. OpenAPI describe APIs HTTP. GraphQL y gRPC tienen sus propios lenguajes de esquema.

Swagger, pruebas de API y monitorización

Una descripción es solo una promesa sobre el comportamiento. Las pruebas de API comprueban esa promesa antes del lanzamiento y la monitorización de APIs la comprueba de forma continua en producción. LoadFocus API Monitoring puede importar una especificación OpenAPI 3.x o Swagger 2.0 y generar un monitor por operación, con comprobaciones del código de estado, el cuerpo, las cabeceras y el tiempo de respuesta. Las comprobaciones gratuitas se ejecutan cada 5 minutos.

La misma descripción puede servir de base para pruebas de rendimiento: importar cURL, HAR, Postman y OpenAPI en pruebas de carga (en inglés) explica cómo. Para probar peticiones a mano, consulta la guía del probador de APIs online (en inglés).

Preguntas frecuentes sobre Swagger y OpenAPI

¿Swagger es lo mismo que OpenAPI?

No exactamente. OpenAPI es la especificación. Swagger es el nombre original de esa especificación y hoy el de las herramientas que la rodean, como Swagger UI y Swagger Editor.

¿Es gratis Swagger?

Swagger UI y las demás herramientas de código abierto se pueden usar gratis. SmartBear también vende productos alojados; consulta su web para ver los planes actuales.

¿Qué versión debo usar?

Usa una versión 3.x actual si tus herramientas la admiten. La última publicada es la 3.2.1; muchas herramientas siguen apuntando a la 3.0 o la 3.1, así que comprueba qué aceptan tu generador de documentación y tu generador de código.

¿Swagger o Postman?

Cumplen funciones distintas. OpenAPI describe la API y Postman es un cliente para explorarla y probarla. Postman puede trabajar a partir de una descripción OpenAPI.

¿Puedo usar OpenAPI para GraphQL o gRPC?

No. OpenAPI describe APIs HTTP. GraphQL usa su propio lenguaje de esquema y gRPC usa Protocol Buffers.

¿Puedo probar mi API contra la especificación?

Sí. Las herramientas de pruebas de contrato comparan las respuestas reales con la descripción, y un monitor generado desde la especificación comprueba la API en vivo de forma programada.