Cómo la IA genera endpoints desde 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:36

Cómo la IA genera endpoints desde OpenAPI

Curso de API First

Clase 8 de 19

Clase 8 / 19

Recursos

Diseñar una API antes de escribir código en Express es posible cuando defines el contrato en OpenAPI y dejas que la inteligencia artificial traduzca esa especificación a código funcional. Aquí verás cómo construir y probar endpoints para obtener y actualizar usuarios por ID, respetando reglas de validación declaradas en el archivo openapi.json.

¿Cómo definir un endpoint POST en OpenAPI antes de codificar?

El reto inicial pedía documentar el método para actualizar un usuario por ID dentro del archivo OpenAPI antes de tocar Express. Esa práctica fija el contrato y evita ambigüedades cuando la herramienta de IA genere el código.

La especificación necesitaba estos elementos clave:

Un parámetro id marcado como requerido, con su tipo de dato definido.
Un request body obligatorio con la información a actualizar del usuario.
Un esquema con campos name, age y email, donde el nombre tiene mínimo 2 caracteres, el correo cumple formato email y la edad mínima es 18.
Respuestas tipadas: 200 con el usuario actualizado (id, name, age, email) y 404 cuando el usuario no existe.

¿Qué es un request body en OpenAPI? Es el bloque de datos que el cliente envía al servidor en operaciones como POST o PUT. En este caso contiene los campos del usuario que quieres actualizar y puede marcarse como requerido para que la API rechace peticiones vacías.

¿Cómo generar el código de Express desde la especificación con IA?

Una vez que el contrato vive en openapi.json, basta con seleccionar el bloque de users y pedirle a la herramienta de inteligencia artificial que construya el endpoint en index.js cumpliendo las reglas de OpenAPI. El prompt apunta directamente a la línea donde se declara el punto de entrada /users/{id} para que la IA tenga contexto completo.

El resultado generado incluye varias piezas:

Una simulación de base de datos con un array en memoria.
Un endpoint GET /users/:id que convierte el parámetro a entero y busca al usuario.
Una validación que responde 404 cuando el usuario no existe.
Un endpoint PUT (o POST según el diseño) que localiza al usuario, aplica el update y devuelve el JSON actualizado.

Un detalle a tener presente es que la validación del esquema ocurre a nivel API, pero también necesitas verificar la existencia del usuario en tu fuente de datos, que aquí es solo un array en memoria.

¿Por qué revisar el código que entrega la IA?

El mismo prompt puede dar resultados distintos si cambias valores o si la indicación no es clara. Por eso conviene leer línea por línea lo que la herramienta propone, confirmar que respeta el contrato y ajustar lo que haga falta. Si quieres mejorar tus instrucciones, el curso de Prompt Engineering en Platzi profundiza en esa habilidad.

¿Cómo simular la base de datos para probar la API?

Como el foco está en el diseño desde OpenAPI y no en la persistencia, la solución usa un array con usuarios precargados que cumplen el esquema: un id, un nombre, una edad mayor a 18 y un correo válido. Esa estructura permite probar los endpoints sin levantar un motor de base de datos.

Entre los usuarios de prueba aparece María García con id 2, que sirve para validar tanto la lectura como la actualización.

¿Cómo probar los endpoints en Swagger?

Con el servidor corriendo y sin errores en la terminal, la documentación generada por Swagger muestra los dos recursos listos: obtener un usuario por ID y actualizar uno por ID. Desde ahí puedes ejecutar peticiones reales contra la API.

Estas son las pruebas que confirman que el contrato se cumple:

GET con id 1 devuelve solo el id y el nombre, tal como definiste en la respuesta 200 del OpenAPI.
GET con id 20 responde 404 con el mensaje de usuario no encontrado.
PUT con id 2 enviando un payload válido actualiza a María García por el nuevo valor y la siguiente lectura confirma el cambio en memoria.
PUT con id 1 enviando un nombre de solo tres caracteres devuelve 400 Bad Request porque rompe la regla de longitud mínima.

¿Qué diferencia hay entre un 400 y un 404 en una API REST? Un 400 indica que la petición está mal formada o no cumple las reglas de validación, como un nombre demasiado corto. Un 404 significa que el recurso solicitado no existe, por ejemplo un usuario con id 20 que no está en la base de datos.

La lógica de validación queda lista sin haber escrito reglas manuales en Express: la especificación OpenAPI dicta el comportamiento y la IA lo traduce a código que respeta esos límites. ¿Qué endpoint vas a documentar primero en tu próximo proyecto?

William Serrano

Hace 6 meses

Aqui el codigo agregado. Es antes de app.listen

const users = [
  {
    id: 1,
    name: "Juan Perez",
    age: 30,
    email: "juan@example.com",
  },
  {
    id: 2,
    name: "María García",
    age: 25,
    email: "maria@example.com",
  },
  {
    id: 3,
    name: "Carlos López",
    age: 35,
    email: "carlos@example.com",
  },
];

app.get('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const user = users.find(u => u.id === userId);

  if (!user) {
    return res.status(404).json({ message: "Usuario no encontrado" });
  } 
  
  res.json({
    id: user.id,
    name: user.name
  });
});

app.post('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  const { name, age, email } = req.body;

  const userIndex = users.findIndex(u => u.id === userId);

  if (userIndex === -1) {
    return res.status(404).json({ message: "Usuario no encontrado" });
  }

  const UpdatedUser = { 
    id: userId, 
    name, 
    age, 
    email 
  };
  users[userIndex] = UpdatedUser;
  res.json(UpdatedUser);
});

William Serrano

Hace 6 meses

Aqui la parte final del yaml que incluye todo el users/[id]:

  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string  
    post:
      summary: update user's name by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        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:    
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  age:
                    type: integer
                  email:
                    type: string
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

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

Cómo la IA genera endpoints desde 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