Comprobación de campos obligatorios de OpenAPI

Las cuatro piezas obligatorias

El valor de info.version es la versión de tu propia API, no la de la especificación OpenAPI. Mucha gente lo omite porque la versión de la especificación ya aparece arriba.

Un ejemplo práctico con todo lo obligatorio ausente

servers:
  - url: https://api.example.com

Este documento diminuto no tiene ninguna de las piezas obligatorias. El informe enumera tres errores:

Cuando falta el objeto info completo, la herramienta informa de ese único error y no enumera por separado el título y la versión. Añade info con ambos campos y la siguiente ejecución informará de los que sigan faltando.

Esqueleto inicial

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Este esqueleto supera todas las comprobaciones de campos obligatorios. Sustituye los nombres por los tuyos y amplía desde ahí. Las respuestas, los esquemas y la seguridad no forman parte de esta comprobación.

Cuándo ejecutar esta comprobación

Ejecútala cuando empieces una spec desde cero, después de generarla a partir del código y antes de enviarla a alguien que la vaya a importar en otra herramienta. Muchos importadores se detienen en el primer campo obligatorio que falte con un mensaje breve, así que detectarlos todos en una sola pasada ahorra varias idas y vueltas. También sirve de recordatorio para quien empieza, que a menudo olvida info.version o deja paths fuera mientras esboza una API.

Cuando los campos obligatorios superen la comprobación, las siguientes mejoras útiles son una description breve bajo info, una entrada servers y un operationId en cada operación. Aquí no se comprueba ninguna de ellas, pero facilitan la lectura y la generación de código cliente.