Validación automática con OpenAPI en Express

Contenido del curso

Introducción y Fundamentos de API First

Herramientas y Validación de APIs

Versionado, Prototipado y Documentación

Validación y Pruebas de Contratos

Seguridad

19
Proteger endpoints con JWT en OpenAPI
07:40 min

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0013:53

Validación automática con OpenAPI en Express

Curso de API First

Clase 6 de 19

Clase 6 / 19

Recursos

Definir un endpoint POST en OpenAPI antes de escribir código en Express te permite validar datos automáticamente, sin escribir validadores manuales para nombre, edad o correo. Si trabajas con Node.js y buscas APIs más limpias, este flujo te ahorra horas de lógica repetitiva.

La idea central es simple: el contrato que defines en el archivo OpenAPI se convierte en la fuente de verdad. Express solo recibe la petición y responde, mientras un validator intercepta cualquier dato que no cumpla las reglas.

¿Cómo se define un endpoint POST en OpenAPI?

Todo arranca en el archivo OpenAPI, donde describes el nuevo path /users con el método post antes de tocar Express.

Dentro de ese path declaras un summary corto como crear un nuevo usuario y un requestBody marcado como required: true. Después defines el content con application/json y, dentro, un schema de tipo object.

El schema necesita dos bloques clave:

required: lista los campos obligatorios, en este caso name, age y email.
properties: describe el tipo y las reglas de cada campo.

Para name defines type: string con minLength: 2. Para age, type: integer con minimum: 18. Para email, type: string con format: email. Esas tres reglas reemplazan validadores manuales que normalmente escribirías en JavaScript.

¿Qué hace el campo required en OpenAPI? Marca qué propiedades del objeto son obligatorias. Si una petición llega sin alguna de ellas, el validator responde con un error 400 antes de llegar a tu lógica.

¿Cómo se documenta la respuesta 201?

En el bloque responses agregas el código 201 con su description y su content en application/json. Aquí está el detalle que suele romperse: las propiedades de la respuesta deben ir dentro de un schema con type: object, no sueltas. Si las pones fuera, el validator lanza un error de esquema al levantar el servidor.

La respuesta declara cuatro propiedades: id como string, name como string, age como integer y email como string. Así el consumidor de la API sabe exactamente qué recibir.

¿Cómo se conecta OpenAPI con Express?

En el archivo de Express creas la ruta con app.post('/users', (req, res) => { ... }). Antes, en la parte superior, agregas el middleware app.use(express.json()) para que el cuerpo JSON llegue parseado a req.body.

Dentro del handler desestructuras name, age y email desde req.body. Y aquí viene lo interesante: no escribes ni un solo if para validar. El validator conectado a OpenAPI ya rechazó cualquier petición que no cumpla el contrato.

El cuerpo del handler queda mínimo:

js app.post('/users', (req, res) => { const { name, age, email } = req.body; const newUser = { id: Date.now().toString(), name, age, email }; res.status(201).json(newUser); });

El id se genera con Date.now().toString() como ejemplo. En un proyecto real, esa lógica conecta con Prisma y una base de datos Postgres para persistir el usuario.

¿Por qué reiniciar el servidor después de cambiar el OpenAPI? Porque el validator lee la especificación al arrancar. Si modificas el archivo mientras npm run dev está corriendo, los cambios pueden no aplicarse hasta levantar el proceso de nuevo.

¿Qué pasa cuando una petición no cumple el contrato?

Aquí se ve el valor real del enfoque. Probando desde la documentación interactiva, si envías un name con una sola letra, la API responde 400 Bad Request con un mensaje claro: el campo debe tener al menos dos caracteres.

Lo mismo ocurre con los otros campos:

Si mandas age menor a 18, el validator indica que el valor mínimo permitido es 18.
Si el email no respeta el formato estándar, devuelve un error de formato.
Si falta cualquier campo obligatorio, la petición se rechaza antes de llegar al handler.

Ninguna de esas validaciones vive en tu código de Express. Todas salen del contrato OpenAPI.

¿Qué ventajas trae validar desde OpenAPI?

Documentar y validar al mismo tiempo cambia la experiencia de quien consume tu API:

Reduces código de validación repetitivo en cada endpoint.
La documentación siempre coincide con el comportamiento real, porque es la misma fuente.
Los errores son consistentes y descriptivos sin esfuerzo extra.
Quien integra tu API sabe de antemano qué enviar y qué recibir.

¿Qué es un schema en OpenAPI? Es la descripción estructurada de un objeto JSON: sus propiedades, tipos de dato, formatos y reglas como longitud mínima o valor mínimo. Funciona como contrato entre cliente y servidor.

Probar el endpoint desde la documentación generada también acelera el desarrollo. Refrescas la página, ves el bloque users con crear un nuevo usuario, ejecutas con datos válidos y obtienes el 201 con el ID del timestamp. Cambias un dato, fuerzas un error y el validator responde sin que toques una línea de Express.

¿Has migrado alguna API existente a este flujo basado en contrato? Cuéntame qué validaciones lograste eliminar de tu código.

Alfonso Vidal Roque Mamani

Hace un año

const express = require('express');

const swaggerUi = require('swagger-ui-express');

const yaml = require('js-yaml'); // Cambia a js-yaml

const fs = require('fs'); // Para leer el archivo

const OpenApiValidator = require('express-openapi-validator');

const app = express();

const port = 3000;

// Carga el YAML como objeto JS

const swaggerDocument = yaml.load(fs.readFileSync('./openapi.yaml', 'utf8'));

// Configura Swagger UI

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.use(express.json());

app.use(

OpenApiValidator.middleware({

apiSpec: swaggerDocument,

validateRequests: true,

validateResponses: true,

ignorePaths: /.*\/docs.*/,

})

);

app.use((err, req, res, next) => {

res.status(err.status || 500).json({

message: err.message,

errors: err.errors,

});

// Endpoints (sin cambios)

app.get('/hello', (req, res) => {

res.json({ message: 'hello world' });

});

app.post('/users', (req, res) => {

const { name, age, email } = req.body;

const newUser = {

id: Date.now().toString(),

name,

age,

email,

};

res.status(201).json(newUser);

});

app.listen(port, () => {

console.log(Server is running on port ${port});

});

.yaml

openapi: 3.1.1

info:

title: API First

version: 1.0.0

description: API First

servers:

- url: http://localhost:3000

components:

schemas:

HelloResponse:

type: object

UserRequest:

type: object

required:

- name

- age

- email

properties:

name:

type: string

minLength: 2

age:

type: integer

minimum: 18

email:

type: string

format: email

UserResponse:

type: object

properties:

id:

type: string

name:

type: string

age:

type: integer

email:

type: string

paths:

/hello:

get:

summary: Hello World

responses:

'200':

description: A successful response

content:

application/json:

schema:

$ref: '#/components/schemas/HelloResponse'

/users:

post:

summary: Crea un nuevo usuario

requestBody:

required: true

content:

application/json:

schema:

$ref: '#/components/schemas/UserRequest' # Reutilizo schema para DRY

responses:

'201':

description: Usuario creado

content:

application/json:

schema:

$ref: '#/components/schemas/UserResponse' # Reutilizo schema

Introducción y Fundamentos de API First

API First con OpenAPI antes de programar

Especificación OpenAPI para documentar APIs RESTful

Configuración inicial de proyecto ExpressJS con especificación OpenAPI

Construcción de API con Express y documentación Swagger

Herramientas y Validación de APIs

Validación automática con Express OpenAPI Validator

Validación automática con OpenAPI en Express

Múltiples respuestas HTTP en OpenAPI

Cómo la IA genera endpoints desde OpenAPI

Esquemas reutilizables de productos en OpenAPI

Endpoints de productos con esquemas reutilizables

API First con IA: construye CRUD sin codificar

Versionado, Prototipado y Documentación

Versionado de APIs con OpenAPI

Cómo crear un mock server con Prism CLI

Organización y mejora de documentación OpenAPI

Agregar ejemplos reales en especificaciones OpenAPI

Validación y Pruebas de Contratos

Errores en OpenAPI que Swagger Editor detecta

Importación de OpenAPI a Postman para automatizar pruebas

Pruebas de API con Newman en tu pipeline

Seguridad

Proteger endpoints con JWT en OpenAPI

Validación automática con OpenAPI en Express

Progreso del curso

Introducción y Fundamentos de API First

Herramientas y Validación de APIs

Versionado, Prototipado y Documentación

Validación y Pruebas de Contratos

Seguridad

Recursos

Recursos