## ¿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](/kb/es/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:

```json
{
  "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](/kb/es/skills)** | Markdown + frontmatter | *Cómo usar este servicio en prosa* | Elegir qué endpoint llamar |
| **Manifiesto [MCP](/kb/es/mcp)** | JSON-RPC | *Herramientas expuestas sobre conexión persistente* | Llamar al servidor como herramienta |
| **[llms.txt](/kb/es/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](/kb/es/x402), [L402](/kb/es/l402), [MPP](/kb/es/mpp), [SPT](/kb/es/spt)), y cualquier URL de pago.

```json
{
  "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](/kb/es/skills)?**
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](https://www.openapis.org/) — spec oficial y docs
- [Swagger Editor](https://editor.swagger.io/) — escribir y validar specs
- [SKILL.md](/kb/es/skills) — capa de prosa acompañante para agentes
- [x402](/kb/es/x402) — protocolo de pago que se integra vía `x-payment-info`