OpenAPI y Swagger: arrancar escenarios de rendimiento con ayuda de IA

Tu openapi.json tiene doscientas operaciones y el sprint pide «una prueba de carga para el release». Pegar el spec entero en un chat de IA produce un script alfabético que pasa lint pero no refleja ningún journey real—y mezcla auth, payloads obsoletos y rutas fuera de alcance. Arrancar pruebas de rendimiento desde OpenAPI con IA funciona cuando el spec está actualizado y tratas la IA como formateador, no arqueólogo.

En esta guía verás qué fragmentos incluir en el prompt, cómo partir specs en journeys antes de generar, qué la IA no puede inferir, una secuencia de bootstrap con smoke obligatorio y controles de drift para que CI no quede desincronizado del contrato.

Por qué OpenAPI + IA falla sin journeys explícitos

A nivel de contrato, las operaciones pueden estar bien tipadas. A nivel de prueba de carga, lo que importa es orden de usuario: onboard → configurar → pagar—not orden alfabético de paths. Los modelos defaultean a listar /a, /b, /c porque es la estructura del JSON, no porque refleje tráfico de producción.

Además, los specs omiten lo que más rompe bajo carga:

• Reglas ocultas de gateway, WAF o headers obligatorios no documentados.
• Rate limits ausentes del spec—cruza con límites de tasa.
• Ejemplos de payload stale que devuelven 422 en staging actual.

Piensa en OpenAPI como el índice de un libro y los journeys como los capítulos que lees en orden—la IA necesita los capítulos, no el índice completo impreso en una página.

Qué incluir en el prompt

• Sello de versión o hash git del spec.
• Lista de operationIds en alcance para este release—not toda la superficie API.
• Resumen del esquema de auth: OAuth2 client credentials vs nombre del header API key.
• Orden de operaciones por journey, no por path alfabético.

Pide k6 que refleje orden de journey para cada historia de usuario. Combina el output con tipos de escenario k6 antes de escalar tráfico.

Implementación práctica: secuencia de bootstrap

Script de ejemplo (ilustrativo—no es una prueba lista para producción). Generado conceptualmente desde un journey «onboard → checkout» con dos operationIds.

Qué demuestra este ejemplo:

• Módulo delgado por journey—no un monolito con todas las operaciones.
• Variables capturadas entre pasos (userId, token).
• Checks más allá de 200—status y forma mínima de respuesta.
• Tags por operación para alinear reportes con operationId.

import http from 'k6/http';
import { check, sleep } from 'k6';

const BASE = __ENV.API_BASE || 'https://staging.example.com';

export const options = {
  scenarios: {
    onboard_checkout: {
      executor: 'constant-arrival-rate',
      rate: 5,
      timeUnit: '1s',
      duration: '3m',
      preAllocatedVUs: 5,
      maxVUs: 20,
      exec: 'onboardThenCheckout',
      tags: { journey: 'onboard_checkout' },
    },
  },
  thresholds: {
    'http_req_duration{operation:createUser}': ['p(95)<500'],
    'http_req_duration{operation:checkout}': ['p(95)<800'],
    http_req_failed: ['rate<0.01'],
  },
};

export function onboardThenCheckout() {
  const createRes = http.post(
    `${BASE}/users`,
    JSON.stringify({ email: `vu${__VU}-${__ITER}@example.com`, plan: 'trial' }),
    {
      headers: { 'Content-Type': 'application/json', 'X-Api-Key': __ENV.API_KEY },
      tags: { operation: 'createUser' },
    }
  );
  check(createRes, { 'user created': (r) => r.status === 201 });
  const userId = createRes.json('id');

  sleep(0.5);

  const checkoutRes = http.post(
    `${BASE}/users/${userId}/checkout`,
    JSON.stringify({ sku: 'SKU-100' }),
    {
      headers: { 'Content-Type': 'application/json', 'X-Api-Key': __ENV.API_KEY },
      tags: { operation: 'checkout' },
    }
  );
  check(checkoutRes, { 'checkout ok': (r) => r.status >= 200 && r.status < 300 });
}

Secuencia de bootstrap recomendada

1. Parte el spec en journeys (onboard → configure → pay) y genera un módulo por bundle.
2. Smoke 1 VU por journey; corrige correlación y ejemplos contra staging real.
3. Mapea journeys a executors según la pregunta de tráfico (RPS estable vs rampa).
4. Valida ejemplos contra una captura reciente de staging o Postman—ajusta checks antes de escalar.
5. Al actualizar OpenAPI, regenera desde diff—not desde memoria; guarda hash del spec junto al script en git.

Patrones que funcionan

• Diff-aware prompts cuando solo cambiaron dos operaciones—no regenerar suites enteras.
• Colección Postman como verdad de ejecución si existe; OpenAPI solo para gaps de cobertura (Postman a k6).
• Fallar builds en CI cuando openapi.json deriva de main sin PR de script de perf coincidente.

Anti-patrones a evitar

• Confiar en checks default status === 200 cuando la API devuelve 202 o cuerpos vacíos.
• Generar contra Prism/Mockoon y reportar throughput como si fuera prod—etiqueta resultados «solo contrato» (mocks vs dependencias reales).
• Pegar fragmentos desordenados de specs multi-archivo en mensajes sueltos—zip el directorio relevante antes de promptear.

Marco de decisión: OpenAPI vs colección vs hand-code

Usa OpenAPI + IA si el spec está versionado, los journeys están explícitos y correrás smoke 1 VU antes de cualquier gate de carga.

Prefiere colección importada si staging ya validó cookies, redirects y variables capturadas que el spec no documenta.

Observabilidad, documentación y siguientes pasos

Antes de confiar en números de throughput:

• Registra hash del spec y operationIds incluidos en el PR.
• Compara payloads generados con captura HAR redactada de staging.
• Documenta si el run fue contra mock o stack real.
• Añade tags operation:* alineados a APM donde existan.
• Automatiza smoke post-merge de API en CI (CI/CD).

Para equipos con GraphQL además de REST OpenAPI, mantén suites paralelas—consulta GraphQL y k6 cuando el estilo de API difiera.

Cómo Performate acelera bootstrap OpenAPI → k6

Ejemplo: de spec a smoke en un workspace

1. Importa OpenAPI (o Swagger) y conserva paths versionados en carpetas por dominio. Problema resuelto: una fuente de verdad visible junto al borrador IA.
2. Selecciona operationIds del release en el asistente con patrón de prompt journey. Problema resuelto: output modular, no blob alfabético.
3. Corre 1 VU en el runner de escritorio y corrige variables capturadas. Problema resuelto: errores de ejemplo stale antes de escalar.
4. Exporta k6 para el pipeline cuando smoke pase. Problema resuelto: local y CI comparten el mismo script revisado.

Cierre

Arrancar pruebas de rendimiento desde OpenAPI con IA tiene éxito cuando los specs están versionados, los journeys son explícitos y los smoke runs—not la prosa—prueban corrección.

Antes del próximo release, lista los operationIds en alcance, genera un módulo por journey y corre 1 VU contra staging real—anota qué ejemplo del spec ya no coincide con la API viva.

Try Performate free | Book a demo | k6 scenarios