← Base de Conocimientos

OpenAPI — Especificación de API

¿Qué es OpenAPI?

OpenAPI (originalmente Swagger) es la especificación dominante para describir APIs REST en forma legible por máquina. Un documento OpenAPI — típicamente un archivo JSON o YAML en /openapi.json o /swagger.json — enumera cada endpoint, el verbo HTTP, los parámetros que acepta cada uno, el esquema de respuesta, el esquema de autenticación y cualquier extensión personalizada. La versión 3.x es mantenida por la OpenAPI Initiative, un proyecto de la Linux Foundation con contribuyentes de Google, Microsoft, IBM, Postman, SmartBear y otros.

Para los agentes de IA, OpenAPI es la diferencia entre adivinar la superficie de tu API y conocerla. Un agente que puede recuperar tu documento OpenAPI tiene la misma facilidad de primera clase que un SDK generado da a un desarrollador humano.

Por qué OpenAPI importa para los agentes

Los agentes que llaman a APIs REST enfrentan un problema de coste de iteración. Sin schema, el bucle es: adivinar el endpoint → llamarlo → parsear el error → adivinar la forma del parámetro → llamarlo de nuevo → parsear el siguiente error. Tres a cinco round-trips por endpoint es típico, y el agente quema tokens y tiempo en cada llamada fallida.

Con OpenAPI, el agente puede:

• Elegir el endpoint correcto leyendo los campos summary y description contra la intención del usuario.
• Construir una petición válida al primer intento leyendo el schema de parámetros.
• Parsear respuestas correctamente uniéndose al schema de respuesta.
• Descubrir autenticación desde el objeto securitySchemes — incluyendo requisitos de pago x402 vía la extensión x-payment-info que AgentGrade busca.

Los agentes que encuentran OpenAPI en un sitio tienen éxito en la primera llamada a una tasa medible más alta que los agentes que tienen que scrapear documentación.

Cómo funciona OpenAPI

OpenAPI es un documento JSON o YAML. Abre con metadatos (info, servers), luego enumera cada ruta bajo paths, luego declara schemas reutilizables bajo components. Las herramientas lo leen vía fetch HTTP — no se requiere SDK o parser más allá del manejo estándar de JSON.

Un documento OpenAPI 3.0 mínimo válido:

{
  "openapi": "3.0.3",
  "info": {
    "title": "Catalog API",
    "version": "1.0.0",
    "description": "Search the product catalog and place orders."
  },
  "servers": [
    { "url": "https://api.example.com" }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search the product catalog",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Search results" }
        }
      }
    }
  }
}

La mayoría de frameworks web generan esto automáticamente desde definiciones de ruta (FastAPI en Python, Hono en TypeScript, Echo en Go, springdoc-openapi de Spring en Java). La autoría manual rara vez es necesaria.

OpenAPI vs otras capas de agent-readability

Spec	Formato	Qué responde	Para qué lo usan los agentes
OpenAPI	JSON/YAML	Endpoints, parámetros, tipos, auth	Construir peticiones válidas
SKILL.md	Markdown + frontmatter	Cómo usar este servicio en prosa	Elegir qué endpoint llamar
Manifiesto MCP	JSON-RPC	Herramientas expuestas sobre conexión persistente	Llamar al servidor como herramienta
llms.txt	Markdown	Qué es este sitio	Triage — ¿es relevante?
ai-plugin.json	JSON	Metadata legacy de plugin ChatGPT	Descubrimiento de plugins (deprecado)

OpenAPI es el schema-de-registro. Los otros archivos se refieren a él; los agentes validan contra él.

La extensión x-payment-info

OpenAPI soporta campos de extensión personalizados con prefijo x-. AgentGrade busca un objeto x-payment-info a nivel de operación que declare si un endpoint es pagado, el precio, el protocolo (x402, L402, MPP, SPT), y cualquier URL de pago.

{
  "paths": {
    "/api/order": {
      "post": {
        "summary": "Place an order",
        "x-payment-info": {
          "required": true,
          "protocol": "x402",
          "price_usd": "0.10",
          "currency": "USDC",
          "network": "base"
        }
      }
    }
  }
}

Esto hace que la señal de endpoint pagado sea verificable por máquina sin que el agente necesite emitir una petición sonda.

Quién usa OpenAPI

OpenAPI es genuinamente universal. Plataformas de API principales (Stripe, Twilio, GitHub, Cloudflare, AWS vía su generador OpenAPI) publican specs OpenAPI como referencia canónica. Adopciones principales por framework:

• FastAPI (Python) — genera OpenAPI desde type hints
• Hono + zod — rutas TypeScript validadas en runtime que emiten OpenAPI
• NestJS (TypeScript) — generación OpenAPI dirigida por decoradores
• Spring Boot + springdoc — OpenAPI basado en anotaciones para Java
• Echo + echo-swagger — generación OpenAPI para Go
• Rails + rswag — generación OpenAPI para Ruby

Cómo añadir OpenAPI a tu servicio

1. Elige un generador. Si tu framework soporta generación OpenAPI automática, úsala. Escribir a mano es propenso a errores.
2. Sírvelo en una ruta estable. /openapi.json es la ubicación convencional.
3. Configura CORS. Permite a los fetchers de agente leer el documento desde contexto de navegador.
4. Declara servers con la URL de producción.
5. Añade campos description. Cada endpoint, cada parámetro.
6. Declara x-payment-info si algún endpoint requiere pago.
7. Enlaza desde llms.txt o SKILL.md. Opcional pero útil.

Errores comunes que detectan los escáneres

• Content-type equivocado — la spec se sirve como text/html (a menudo una página de Swagger UI) en lugar de application/json.
• Spec obsoleta — el archivo lista endpoints que ya no existen u omite nuevos.
• servers[].url faltante — los agentes que leen este campo construyen URLs contra el origen equivocado.
• Sin description en endpoints — los agentes no pueden elegir entre endpoints similares.
• x-payment-info declarado no coincide con sonda en vivo.
• CORS bloquea el fetch.

FAQ

¿Cuál es la diferencia entre OpenAPI y Swagger?

"Swagger" fue el nombre original; en 2015 fue renombrado a OpenAPI cuando se donó a la Linux Foundation. SmartBear retiene la marca "Swagger" para herramientas (Swagger UI, Swagger Editor).

¿Necesito OpenAPI si tengo SKILL.md?

Envía ambos si tienes una API. SKILL.md es el "manual de juego" — prosa. OpenAPI es el "contrato" — formal.

¿Debo servir en /openapi.json o /.well-known/openapi.json?

/openapi.json en la raíz es la convención dominante.

OpenAPI 3.0 vs 3.1 vs 2.0 — ¿importa?

3.1 es actual; 3.0 está bien y ampliamente soportado. 2.0 (formato "Swagger 2.0" original) aún se reconoce pero deberías migrar.

¿Puedo servir OpenAPI para una API GraphQL?

OpenAPI describe REST. Para GraphQL, los agentes introspectan el schema directamente vía el endpoint GraphQL.

¿AgentGrade penaliza sitios con info de pago solo declarada?

Los sitios con OpenAPI declarando x-payment-info pero sin verificación en vivo puntúan positivamente pero por debajo de los sitios donde la sonda en vivo confirma el protocolo declarado.

¿Qué pasa con x-mcp-server u otras extensiones?

El prefijo x- de OpenAPI es abierto. AgentGrade busca x-payment-info actualmente.

¿Cuán grande puede ser una spec OpenAPI antes de que los agentes tengan problemas?

Specs de varios MB son comunes en plataformas de API grandes (la de Stripe es ~10MB). Los agentes generalmente fetcheen y parsean bien.

Madurez de la especificación

Estándar universal de la industria. OpenAPI 3.x es mantenido por la OpenAPI Initiative bajo la Linux Foundation.

Saber más

• OpenAPI Specification — spec oficial y docs
• Swagger Editor — escribir y validar specs
• SKILL.md — capa de prosa acompañante para agentes
• x402 — protocolo de pago que se integra vía x-payment-info

Relacionado: ¿Qué es la preparación para agentes de IA?