Esquemas reutilizables de productos en OpenAPI

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:009:15

Esquemas reutilizables de productos en OpenAPI

Curso de API First

Clase 9 de 19

Clase 9 / 19

Recursos

Diseñar un esquema reutilizable en OpenAPI te permite estandarizar la estructura de tus datos, reducir repeticiones y validar campos antes de escribir una sola línea de código. Aquí aprenderás a construir un schema de producto dentro de la sección components, aplicando tipos de datos, validaciones y reglas que luego podrás invocar desde cualquier endpoint de tu API.

Por qué usar components en OpenAPI

La sección components actúa como una biblioteca central donde defines una vez y reutilizas en todos los paths y respuestas de tu documento.

En lugar de repetir la misma estructura en cada solicitud, defines un esquema base y lo referencias. Eso simplifica el mantenimiento y evita inconsistencias cuando tu API crece.

¿Qué son los components en OpenAPI? Son bloques reutilizables que centralizan esquemas, respuestas y parámetros para que puedas invocarlos desde distintos endpoints sin duplicar código.

Cómo definir el esquema base de un producto

Antes de escribir el esquema conviene sentarse a diseñar: qué campos tendrá el producto, cuáles son obligatorios y qué validaciones aplican a cada uno [03:45].

El esquema arranca con el nombre products, el tipo object y un bloque required que marca los campos obligatorios:

name: identifica el producto.
price: define el valor monetario.
category: clasifica el producto dentro de un grupo.

yaml products: type: object required: - name - price - category properties: ...

Esto no significa que el producto solo tenga tres campos. Significa que sin esos tres, el producto no es válido.

Cómo aplicar validaciones a strings y números

Cada propiedad necesita su tipo y sus reglas. Para name defines type: string con minLength: 2 y maxLength: 40, evitando nombres demasiado cortos o exageradamente largos.

Para analizar ese máximo puedes apoyarte en una inteligencia artificial que revise tu catálogo y te sugiera el promedio real de caracteres [05:20].

En description usas un string con maxLength más generoso, entre 200 y 500 caracteres, porque ahí describes el producto a fondo.

Para price el tipo es number con dos reglas clave:

minimum: 0 para no permitir precios negativos.
multipleOf: 0.01 para garantizar dos decimales.

yaml price: type: number minimum: 0 multipleOf: 0.01

Cómo restringir valores con enum y arrays

La propiedad category es un string con valores predefinidos usando enum. Así limitas las opciones a un grupo cerrado:

yaml category: type: string enum: - electronics - books - ropa - food

Para tags defines un array cuyos items son string, con minItems: 1. La regla obliga a que cada producto tenga al menos una etiqueta [07:50].

¿Cómo se valida un array en OpenAPI? Defines type: array, especificas el tipo de los items y agregas reglas como minItems o maxItems para controlar cuántos elementos acepta.

Cómo manejar booleanos, objetos dinámicos y arrays anidados

No todos los campos siguen el mismo patrón. Algunos necesitan flexibilidad, otros estructura estricta.

Booleanos y objetos con propiedades dinámicas

El campo inStock se resuelve con un simple type: boolean. Existe o no existe stock, sin más matices.

Para specifications el reto es distinto: cada producto puede tener atributos técnicos diferentes. Aquí entra additionalProperties:

yaml specifications: type: object additionalProperties: type: string

Eso permite que el objeto acepte cualquier clave adicional siempre que su valor sea un string. Cuida la ortografía al escribirlo, porque un typo rompe la validación.

Arrays de objetos para reseñas

Las calificaciones requieren una estructura más compleja: un array donde cada ítem es un objeto con sus propios campos obligatorios.

yaml ratings: type: array items: type: object required: - score - comment properties: score: type: integer minimum: 1 maximum: 5 comment: type: string maxLength: 200

El score se restringe a un integer entre 1 y 5. El comment es un string con tope de 200 caracteres para mantener las reseñas concisas [10:15].

Qué ganas al diseñar antes de codear

Llegar a este esquema implica una fase previa de diseño donde defines tipos, refinas valores requeridos y ajustas propiedades a casos de uso reales: rangos de precio, decimales monetarios, categorías cerradas, etiquetas mínimas, control de stock y estructura de reseñas.

Cada validación responde a una decisión de producto, no a una convención arbitraria. Por eso el contrato de tu API queda claro antes de tocar el código que lo implementa.

Con este esquema reutilizable listo, el siguiente paso es pedirle a una inteligencia artificial que actualice el documento OpenAPI usando esta estructura como base. ¿Cómo organizarías tú las categorías y validaciones de tu propio catálogo? Cuéntalo en los comentarios.

Edgard Javier Rivera Florez

Hace un año

Recursos: Openapi:

openapi: 3.1.1

info:

title: Example API

version: 1.0.0

description: This is an example API to demonstrate OpenAPI specification.

servers:

- url: http://localhost:3000

description: Ambiente Local para pruebas

components:

schemas:

HelloResponse:

type: object

properties:

message:

type: string

example: Hello, World!

required:

- message

pathraiz:

type: object

properties:

message:

type: string

example: example curso platzi

required:

- message

users:

type: object

properties:

message:

type: string

example: Crear usuario!

required:

- message

securitySchemes:

ApiKeyAuth:

type: apiKey

in: header

name: X-API-KEY

paths:

/hello:

get:

summary: Hello World

responses:

'200':

description: A succesfull response

content:

application/json:

schema:

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

/pathraiz:

get:

summary: path raiz.

responses:

'200':

description: A successful response

content:

application/json:

schema:

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

/users:

post:

summary: Create a new user

requestBody:

content:

application/json:

schema:

type: object

required:

- name

- age

- email

properties:

name:

type: string

minLength: 2

age:

type: integer

minimum: 18

email:

type: string

format: email

responses:

'201':

description: User creado con exito

content:

application/json:

schema:

type: object

properties:

id:

type: integer

name:

type: string

age:

type: integer

email:

type: string

/users/{id}:

get:

summary: Obtener un usuario por ID

parameters:

- name: id

in: path

required: true

schema:

type: integer

responses:

'200':

description: Usuario encontrado con exito

content:

application/json:

schema:

type: object

properties:

id:

type: integer

name:

type: string

'404':

description: User no encontrado

content:

application/json:

schema:

type: object

properties:

message:

type: string

example: User not found

/usersd/{id}:

delete:

summary: Eliminar un usuario por ID

parameters:

- name: id

in: path

required: true

schema:

type: integer

responses:

'200':

description: Usuario eliminado con exito

content:

application/json:

schema:

type: object

properties:

message:

type: string

example: User deleted successfully

'404':

description: User no encontrado

content:

application/json:

schema:

type: object

properties:

message:

type: string

example: User not found

/usersp/{id}:

put:

summary: Actualizar un usuario por ID

parameters:

- name: id

in: path

required: true

schema:

type: integer

requestBody:

required: true

content:

application/json:

schema:

type: object

properties:

name:

type: string

minLength: 2

age:

type: integer

minimum: 18

email:

type: string

format: email

responses:

'200':

description: Usuario actualizado con exito

content:

application/json:

schema:

type: object

properties:

id:

type: integer

name:

type: string

age:

type: integer

email:

type: string

'404':

description: User no encontrado

content:

application/json:

schema:

type: object

properties:

message:

type: string

example: User not found

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

Esquemas reutilizables de productos en OpenAPI

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