¿Cuáles son las diferencias entre OpenAPI 2.0 y 3.0? #

La especificación OpenAPI (OAS) se ha consolidado como una herramienta potente para crear una interfaz estandarizada e independiente del lenguaje para las API RESTful. Como quizá ya sepas, OpenAPI 2.0, antes conocido como Swagger, sentó las bases de la documentación moderna de las API y ofreció directrices claras para describir, producir, consumir y visualizar servicios web RESTful. Sin embargo, el salto a OpenAPI 3.0 trajo consigo revisiones sustanciales, mejoras y nuevas funcionalidades que ampliaron de forma significativa sus capacidades. En este artículo exploramos las principales diferencias entre OpenAPI 2.0 (Swagger) y OpenAPI 3.0 para ayudarte a afrontar la transición y comprender las mejoras.

Tabla de contenido #

• Manejo de esquemas
• Rutas y operaciones de la API
• Definiciones de seguridad
• Cuerpos de solicitud
• Respuestas
• Componentes
• Links
• Callbacks
• Ejemplos
• Cambios varios
• Conclusión

Manejo de esquemas #

Tipos de datos y formatos #

Uno de los cambios clave de OpenAPI 3.0 es el manejo más amplio y flexible de los tipos de datos y los formatos. OpenAPI 3.0 extiende JSON Schema para ofrecer formas más completas de definir estructuras de datos.

OpenAPI 2.0:

type: integer
format: int32

OpenAPI 3.0:

type: integer
format: int32

La diferencia radica en el alcance de la compatibilidad con JSON Schema; OpenAPI 3.0 espera que JSON Schema gestione las definiciones, y sirve de base para casi todos los elementos que describen datos.

Propiedades que admiten valores nulos #

En OpenAPI 2.0, la forma de indicar que un valor podía ser null era menos directa y solía requerir soluciones alternativas. OpenAPI 3.0 introduce una propiedad nullable para mayor claridad.

OpenAPI 2.0: (con solución alternativa)

type: object
properties:
  name:
    type: string
    x-nullable: true

OpenAPI 3.0:

type: object
properties:
  name:
    type: string
    nullable: true

Más información sobre JSON Schema.

Rutas y operaciones de la API #

Parámetros de ruta #

La forma de definir los parámetros de ruta es similar en ambas versiones, pero OpenAPI 3.0 ofrece mayor flexibilidad.

OpenAPI 2.0:

paths:
  /users/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        type: string

OpenAPI 3.0:

paths:
  /users/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string

El cambio más notable es que el campo type se sustituye por un objeto schema, lo que se ajusta a un sistema de definición de esquemas más coherente.

Definiciones de seguridad #

En OpenAPI 2.0, las definiciones de seguridad se gestionaban de forma global y con flexibilidad limitada. OpenAPI 3.0 mejora estas funcionalidades al ofrecer controles más precisos.

OpenAPI 2.0:

securityDefinitions:
  api_key:
    type: apiKey
    name: api_key
    in: header
  petstore_auth:
    type: oauth2
    authorizationUrl: https://petstore.swagger.io/oauth/authorize
    flow: implicit

OpenAPI 3.0:

components:
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://petstore.swagger.io/oauth/authorize
          scopes:
            write:pets: modify pets in your account

El objeto securityDefinitions se sustituyó por components.securitySchemes, lo que amplía las capacidades para definir y gestionar la seguridad.

Cuerpos de solicitud #

Podría decirse que uno de los cambios más significativos es la forma en que OpenAPI 3.0 maneja los cuerpos de solicitud. OpenAPI 2.0 usaba parameters para gestionar todas las entradas de datos, incluidos el contenido del cuerpo y los datos de formulario.

OpenAPI 2.0:

paths:
  /pets:
    post:
      parameters:
        - in: body
          name: pet
          required: true
          schema:
            $ref: '#/definitions/Pet'

OpenAPI 3.0:

paths:
  /pets:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'

En OpenAPI 3.0, la introducción del objeto requestBody ofrece una forma más clara y estructurada de definir el contenido del cuerpo, asociándolo a tipos de medios específicos.

Respuestas #

La estructura de las respuestas en OpenAPI 3.0 ofrece mayor granularidad para definir respuestas según el tipo de contenido. Aunque los principios básicos siguen siendo los mismos, las mejoras sutiles aportan mejor legibilidad y facilidad de gestión.

OpenAPI 2.0:

paths:
  /pets:
    post:
      responses:
        200:
          description: Successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Pet'

OpenAPI 3.0:

paths:
  /pets:
    post:
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'

OpenAPI 3.0 utiliza el objeto content, lo que permite definir de forma más explícita las descripciones y los tipos de contenido.

Componentes #

La introducción del objeto components en OpenAPI 3.0 consolida componentes reutilizables como esquemas, respuestas, parámetros, ejemplos y definiciones de seguridad.

OpenAPI 3.0:

components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  responses:
    NotFound:
      description: Resource not found

Esta reorganización mejora la modularidad y el mantenimiento de la documentación de la API al permitir más piezas reutilizables.

Links #

Los links de OpenAPI 3.0 permiten describir mejor las relaciones entre operaciones, lo que aporta una visión contextual más completa y mayor claridad de navegación.

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          links:
            address:
              operationId: getUserAddress
              parameters:
                userId: $response.body#/id

Los links permiten describir vínculos dinámicos entre operaciones, lo que mejora la capacidad de descubrimiento y la usabilidad de la API.

Callbacks #

Una de las funcionalidades más sofisticadas de OpenAPI 3.0 es la compatibilidad con callbacks, que permite especificar operaciones asíncronas.

paths:
  /subscribe:
    post:
      summary: Subscribe to event notifications
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                callbackUrl:
                  type: string
      responses:
        '201':
          description: Subscription created
      callbacks:
        callbackEvent:
          '{$request.body#/callbackUrl}':
            post:
              requestBody:
                description: Callback payload
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        eventId:
                          type: string
              responses:
                '200':
                  description: OK

Esto permite a los desarrolladores capturar las URL de callback definidas por el cliente, lo que mejora la compatibilidad con escenarios similares a los webhooks.

Ejemplos #

Ambas especificaciones admiten ejemplos, pero OpenAPI 3.0 ofrece más estructura y flexibilidad con la introducción de la palabra clave examples dentro del objeto content.

OpenAPI 3.0:

paths:
  /user:
    get:
      responses:
        '200':
          description: A user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                user:
                  summary: A user example
                  value: {
                    "name": "John Doe",
                    "id": 123
                  }

Esto permite incluir varios ejemplos y documentar mejor distintos casos de uso o escenarios.

Cambios varios #

Etiquetas e ID de operación #

Las etiquetas y los ID de operación de OpenAPI 3.0 son ahora más versátiles y ofrecen mejores formas de describir y organizar las API.

Descripciones mejoradas #

Ahora pueden colocarse descripciones en varios campos de la especificación, lo que permite una documentación más detallada.

Obsolescencia #

Ahora es posible marcar explícitamente como obsoletas las operaciones y los parámetros con la palabra clave deprecated.

paths:
  /pet:
    get:
      deprecated: true

Reescritura de otros elementos #

Otros elementos, como los encabezados, los datos de formulario y las reglas de serialización de parámetros, también se han revisado para lograr mayor coherencia y estructura.

Conclusión #

La transición de OpenAPI 2.0 a 3.0 introdujo cambios fundamentales que simplificaron las descripciones de las API y mejoraron la flexibilidad, el nivel de detalle y la estructura de su documentación. Al adoptar OpenAPI 3.0, los desarrolladores pueden aprovechar funcionalidades mejoradas para el manejo de esquemas, la gestión de solicitudes y respuestas, la vinculación de operaciones y los callbacks asíncronos.

Para profundizar y consultar más información, visita la OpenAPI Initiative y la documentación de la especificación OpenAPI.

Adoptar estos cambios puede contribuir en gran medida a que tus API estén bien documentadas, estandarizadas y listas para una integración completa.

Si te gustó este artículo, compártelo o consulta más recursos para mejorar tus habilidades de desarrollo y documentación de API.

Última actualización: 21 de mayo de 2024.