OpenAPI

``

Conceptos clave

OpenAPI es una especificación estándar para describir APIs HTTP de forma legible por humanos y máquinas. Define de manera formal:

  • Endpoints disponibles
  • Parámetros de entrada
  • Respuestas posibles
  • Modelos de datos
  • Mecanismos de autenticación
  • Versionado y metadatos de la API

Es la base del enfoque API First, donde el contrato se diseña antes de implementar el backend o los clientes.

Relación con Swagger

  • Swagger es el ecosistema de herramientas alrededor de OpenAPI
  • OpenAPI es la especificación
  • Swagger UI permite visualizar y probar la API
  • Swagger Editor permite diseñar el contrato en YAML o JSON

En la práctica, ambos términos se usan juntos, aunque técnicamente no son lo mismo.

Estructura de un documento OpenAPI

Un archivo OpenAPI (normalmente en YAML) se compone de varias secciones principales:

Metadatos

  • Nombre de la API
  • Versión
  • Descripción
  • Contacto y licencia

Servidores

  • URLs base donde se expone la API
  • Soporte para múltiples entornos (dev, staging, prod)

Paths (endpoints)

  • Rutas HTTP (/users, /orders/{id})
  • Métodos (GET, POST, PUT, DELETE)
  • Parámetros de ruta, query y headers

Respuestas

  • Códigos HTTP (200, 400, 404, 500)
  • Estructura de la respuesta
  • Tipos MIME (application/json)

Componentes

  • Esquemas reutilizables (modelos de datos)
  • Parámetros comunes
  • Respuestas estándar
  • Security schemes (JWT, OAuth2, API Keys)

Modelado de datos

  • Basado en JSON Schema
  • Soporta validaciones:
    • Tipos (string, number, array)
    • Restricciones (minLength, pattern, enum)
  • Permite composición (oneOf, anyOf, allOf)

Esto garantiza contratos fuertes entre backend y frontend.

OpenAPI y estándares REST

OpenAPI no impone REST, pero encaja perfectamente con sus principios:

  • Uso correcto de métodos HTTP
  • Recursos identificables por URL
  • Stateless
  • Códigos de estado semánticos

Ayuda a documentar APIs REST de forma consistente y verificable.

OpenAPI Generator

Herramienta clave del ecosistema para generar código automáticamente.

  • Genera clientes y servidores
  • Soporta múltiples lenguajes y frameworks
  • Reduce errores de implementación manual
  • Asegura que el código siga el contrato OpenAPI
[CLI Installation OpenAPI Generator](https://openapi-generator.tech/docs/installation)

Lenguajes y plataformas comunes

  • Java (Spring, Quarkus, Micronaut)
  • TypeScript (Fetch, Axios, Angular)
  • Maven / Gradle
  • Definiciones desde YAML o JSON

Generación de clientes

  • Clientes HTTP tipados
  • Manejo automático de:
    • Endpoints
    • Parámetros
    • Respuestas
    • Errores
  • Muy usado en frontend y microservicios

Esto elimina duplicación y desincronización entre equipos.

Generación de servidores

  • Stubs de controladores
  • Interfaces basadas en el contrato
  • Validación automática de requests y responses

Ideal para flujos API First.

Integración con TypeScript y Zod

  • Generación de clientes TypeScript
  • Integración con validadores runtime como Zod
  • Contratos fuertemente tipados de extremo a extremo

OpenAPI + Zod: Generate The Ultimate TypeScript API Clients Automatically - YouTube

AsyncAPI y OpenAPI

  • OpenAPI describe APIs HTTP síncronas
  • AsyncAPI describe:
    • Eventos
    • Mensajería
    • Streams (Kafka, MQTT, WebSockets)

Ambas especificaciones pueden convivir en arquitecturas modernas.

OpenApi Generator y AsynAPI, un paso más allá del API First. - YouTube

Casos de uso habituales

  • Documentación viva de APIs
  • Contratos entre frontend y backend
  • Generación automática de SDKs
  • Validación de requests/responses
  • Onboarding rápido de nuevos desarrolladores
  • Gobernanza y versionado de APIs

Buenas prácticas

  • Diseñar el contrato antes de implementar
  • Reutilizar esquemas en components
  • Versionar la API explícitamente
  • Validar que implementación y spec coincidan
  • Automatizar generación en CI/CD

OpenAPI — Conceptos avanzados y temas complementarios

$= dv.current().file.tags.join(“ “)

Versionado de APIs

  • Versionado por URL (/v1/users)
  • Versionado por header (Accept: application/vnd.api.v1+json)
  • Versionado semántico del documento OpenAPI
  • Estrategias de deprecación documentadas en la spec

OpenAPI permite marcar endpoints, parámetros o esquemas como deprecated, facilitando la evolución controlada de la API.

Seguridad en OpenAPI

  • Definición formal de mecanismos de autenticación
  • Soporte nativo para:
    • API Keys
    • HTTP Basic / Bearer
    • OAuth 2.0 (flows completos)
    • OpenID Connect
  • Asignación de scopes por endpoint

La seguridad se declara de forma centralizada y reutilizable.

Validación automática

  • Validación de requests entrantes
  • Validación de responses salientes
  • Detección temprana de breaking changes
  • Integración con middlewares y gateways

Permite usar OpenAPI como fuente de verdad contractual.

Testing basado en OpenAPI

  • Generación automática de tests
  • Mocking de endpoints
  • Contract testing
  • Validación de payloads en tests de integración

OpenAPI se convierte en base para pruebas automáticas.

Mock servers

  • Servidores simulados a partir del spec
  • Uso en frontend sin backend real
  • Soporte para ejemplos y respuestas dinámicas
  • Ideal para desarrollo paralelo

Ejemplos y ejemplos enriquecidos

  • Ejemplos por endpoint
  • Ejemplos por esquema
  • Soporte para múltiples ejemplos
  • Mejora de DX y documentación interactiva

Los ejemplos forman parte del contrato, no solo de la UI.

Documentación interactiva avanzada

  • Probar endpoints directamente desde el navegador
  • Autenticación persistente
  • Visualización de modelos y relaciones
  • Soporte para múltiples servidores

OpenAPI actúa como documentación viva.

Extensiones personalizadas (x-*)

  • Extensiones vendor-specific
  • Metadatos para tooling interno
  • Configuraciones para gateways o frameworks
  • No rompen la compatibilidad del estándar

Permiten adaptar OpenAPI a necesidades específicas.

API Governance

  • Estándares internos de diseño
  • Convenciones de nombres
  • Políticas de seguridad
  • Revisión automática del spec

OpenAPI facilita la gobernanza en organizaciones grandes.

Linting y calidad del spec

  • Reglas de consistencia
  • Detección de malas prácticas
  • Enforcement de estándares REST
  • Automatización en pipelines CI/CD

El contrato se trata como código.

Comparación con otras aproximaciones

  • Documentación manual (obsoleta y frágil)
  • Code-first sin contrato explícito
  • GraphQL schemas
  • gRPC y Protobuf

OpenAPI destaca en APIs HTTP públicas y empresariales.

Monorepos y OpenAPI

  • Specs compartidas entre servicios
  • Generación de clientes internos
  • Control de cambios centralizado
  • Versionado coordinado

Ideal para arquitecturas de microservicios.

Performance y tamaño del spec

  • Separación en múltiples archivos
  • Referencia entre documentos
  • Optimización de esquemas
  • Mantenimiento de specs grandes

Facilita escalabilidad documental.

Migración a OpenAPI

  • Desde APIs legacy
  • Desde documentación informal
  • Desde frameworks code-first
  • Adopción progresiva

OpenAPI puede introducirse sin reescritura completa.

Futuro y evolución del estándar

  • Evolución incremental del spec
  • Mejoras en compatibilidad tooling
  • Mayor enfoque en DX
  • Convivencia con AsyncAPI y GraphQL

OpenAPI sigue siendo un pilar del ecosistema API moderno.

OpenAPI — Guía práctica con caso de uso completo

Caso de uso

Diseño API First de una API REST de gestión de usuarios y generación automática de:

  • Backend Java (Spring)
  • Cliente TypeScript
  • Documentación interactiva

La API permitirá:

  • Listar usuarios
  • Crear usuarios
  • Consultar usuario por ID

Definición del contrato OpenAPI

El contrato es la fuente de verdad y se define antes de escribir código.

openapi.yaml

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
  description: API de gestión de usuarios
servers:
  - url: https://api.example.com
paths:
  /users:
    get:
      summary: Listar usuarios
      responses:
        '200':
          description: Lista de usuarios
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Crear usuario
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: Usuario creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: Obtener usuario por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Usuario encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Usuario no encontrado
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string
      required:
        - id
        - email
        - name
    UserCreate:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
      required:
        - email
        - name

`

Generación del backend Java (Spring)

A partir del contrato se generan los stubs del servidor.

Comando OpenAPI Generator (Spring)

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o backend-users-api \
  --additional-properties=interfaceOnly=true

Resultado:

  • Interfaces de controladores
  • Modelos Java
  • Validación automática de requests
  • Contrato obligatorio para implementar

Implementación del controlador

El desarrollador implementa la lógica sin redefinir rutas ni modelos.

UserController.java

@RestController
public class UserController implements UsersApi {

    @Override
    public ResponseEntity<List<User>> usersGet() {
        return ResponseEntity.ok(List.of(
            new User("1", "john@doe.com", "John")
        ));
    }

    @Override
    public ResponseEntity<User> usersPost(UserCreate userCreate) {
        User user = new User("2", userCreate.getEmail(), userCreate.getName());
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }

    @Override
    public ResponseEntity<User> usersIdGet(String id) {
        return ResponseEntity.ok(
            new User(id, "john@doe.com", "John")
        );
    }
}

Generación del cliente TypeScript

El mismo contrato se usa para frontend o integraciones externas.

Comando OpenAPI Generator (TypeScript)

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o frontend-api-client

Uso del cliente TypeScript

El cliente generado ya conoce:

  • Endpoints
  • Tipos
  • Errores

Uso en frontend

import { UsersApi } from './frontend-api-client';

const api = new UsersApi({
  basePath: 'https://api.example.com'
});

const users = await api.usersGet();
const newUser = await api.usersPost({
  email: 'jane@doe.com',
  name: 'Jane'
});

Documentación interactiva

El mismo archivo openapi.yaml se usa para:

  • Swagger UI
  • Swagger Editor
  • Mock servers

Permite probar la API sin escribir clientes manuales.

Mock server para desarrollo

Frontend puede trabajar sin backend real.

Mock con OpenAPI

openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o mock-server

Validación automática en runtime

  • Request inválido → 400 automático
  • Response fuera de contrato → error detectable
  • Modelos siempre coherentes

OpenAPI actúa como firewall de contrato.

Testing basado en contrato

  • Tests de integración alineados al spec
  • Detección de breaking changes
  • Tests generados o asistidos automáticamente

El contrato guía el testing.

Flujo completo recomendado

  • Diseñar openapi.yaml
  • Versionar el spec
  • Generar backend y clientes
  • Implementar lógica
  • Validar en CI/CD
  • Publicar documentación

Este flujo evita desincronización y errores humanos.

OpenAPI — Recursos, estado en 2025 y alternativas

Repositorios oficiales y documentación

  • OpenAPI — Especificación estándar para APIs RESTful.
  • swagger — Ecosistema de herramientas.
  • YAML — Formato habitual de definición de especificaciones.

Documentación interactiva y visualización

  • Swagger UI — Visualiza y prueba tu API desde la especificación. Swagger UI
  • Redoc — Renderizado rápido y estético para documentación de OpenAPI. Redoc
  • ReDocly — Extiende Redoc con gobernanza, versionado y linting. ReDocly
  • DapperDox — Integración de Swagger con Markdown para documentación enriquecida y navegación fácil. DapperDox
  • API Hub, Fern, Speakeasy — Generación de documentación y SDKs automáticos desde OpenAPI (2025). API Hub, Fern, Speakeasy

Diseño y colaboración

  • Postman — Importa specs OpenAPI, genera tests, mocks y documentación colaborativa. Postman
  • Stoplight — Editor visual, diseño, docs y pruebas. Stoplight
  • SwaggerHub — Plataforma colaborativa para diseño y documentación OpenAPI. SwaggerHub
  • Apicurio Studio — Editor colaborativo, validación en tiempo real y soporte OpenAPI/AsyncAPI. Apicurio Studio
  • RepreZen API Studio — Modelado avanzado y documentación. RepreZen

Generación de código

  • OpenAPI Generator — Genera clientes, servidores y documentación desde spec. OpenAPI Generator
  • Swagger Codegen — Alternativa clásica para generación de código. Swagger Codegen
  • Scalar OpenAPI Parser — Parser moderno con soporte de referencia y planificado soporte para OpenAPI 3.2 (2025). Scalar OpenAPI Parser

Mocking y pruebas

  • Prism — Mock server que valida requests contra el spec. Prism
  • Dredd — Valida cumplimiento contra la especificación en CI/CD. Dredd
  • Mockoon — Mock de API con interfaz gráfica. Mockoon
  • Hoverfly, Imposter, Microcks — Herramientas de simulación y test desde specs (listadas en repositorios de recursos 2025). Hoverfly, Imposter, Microcks

Linting, gobernanza y calidad

  • Spectral — Linter JSON/YAML con reglas de estilo y mejores prácticas para OpenAPI. Spectral
  • OpenAPI Enforcer — Valida requests/responses en runtime y tests contra la spec. OpenAPI Enforcer

Alternativas y herramientas adicionales

  • Insomnia — Cliente API moderno con soporte OpenAPI, también útil para pruebas y colaboración ligera. Insomnia
  • Hoppscotch — Cliente web gratuito, ligero y rápido con soporte de varios protocolos. Hoppscotch
  • Bruno — API client con enfoque Git-first para versiones de requests. Bruno
  • Apidog — Plataforma API todo-en-uno con diseño, tests, mocks y gestión de entornos (soporta OpenAPI e integración con IA). Apidog

Alternativas a OpenAPI como especificación

  • AsyncAPI — Standard para APIs event-driven (mensajería y streams), complementario a OpenAPI. AsyncAPI
  • RAML — DSL YAML para describir APIs (menos extendido, sin soporte REST full con HATEOAS). RAML

Integraciones específicas de plataformas

  • Azure: Crear conectores personalizados desde una definición OpenAPI para Logic Apps / Power Apps. Azure Logic Apps
  • Azure AI Foundry permite usar specs OpenAPI como herramientas dentro de proyectos de agentes. Azure AI Foundry

Recursos educativos y comunidad

  • OpenAPI Initiative newsletters y ecosistema activo con eventos y noticias sobre versiones y herramientas. OpenAPI Initiative
  • Repositorios como Track Awesome Lists mantienen listados actualizados de herramientas relacionadas con OpenAPI y APIs. Track Awesome Lists

Recursos académicos recientes (IA y testing)

  • LlamaRestTest: investigación sobre testing de APIs REST usando LLMs para inputs de test generados desde OpenAPI. arXiv
  • SATORI: generación automática de oráculos de test estáticos para APIs REST a partir de OpenAPI. arXiv
  • Multi-agent systems para API-First: automatización avanzada de desarrollo y generación desde spec con feedback de logs. arXiv