Documentacion de APIs
para la era de los agentes
Tu especificacion OpenAPI, transformada en tres salidas: llms.txt optimizado en tokens para agentes de IA, markdown completo para desarrolladores y una landing page en HTML semantico. Un solo comando.
$ npm install swagent Tu documentacion esta hecha para humanos.
Quien la lee ahora?
Los agentes LLM tambien consumen la documentacion de tu API. Swagger UI, Redoc y la documentacion tradicional desperdician miles de tokens en barras de navegacion, esquemas repetidos y formato innecesario. Tus integraciones con IA estan pagando el costo.
{
"openapi": "3.0.2",
"info": {
"title": "Swagger Petstore",
"version": "1.0.27"
},
"paths": {
"/pet": {
"put": {
"tags": ["pet"],
"summary": "Update an existing pet",
"operationId": "updatePet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"400": {
"description": "Invalid ID"
},
"404": {
"description": "Pet not found"
},
"422": {
"description": "Validation exception"
}
},
"security": [
{ "petstore_auth": ["write:pets"] }
]
}
}
}
}# Swagger Petstore - OpenAPI 3.0 v1.0.27
> A sample Pet Store Server based
> on the OpenAPI 3.0 specification.
Base: /api/v3
## Auth
- OAuth2: petstore_auth
- KEY: `api_key` in header
## Conventions
- `*` after field name = required
- All fields string unless noted
- Auth: JWT = Bearer, KEY = API Key
- Common errors: 400/401/404/500
---
## pet
### PUT /pet - Update an existing pet | OAuth2
Body: `{id:integer, name*, category:{id:integer, name},
photoUrls*:[string], tags:[{id:integer, name}],
status:available|pending|sold}`
200: `{id:integer, name*, category:{id:integer, name},
photoUrls*:[string], tags:[{id:integer, name}],
status:available|pending|sold}`One URL. Right format.
LLM agents just read your base URL. No special paths to discover, no extra configuration. Standard HTTP content negotiation delivers the right format automatically, HTML for browsers and token-optimized docs for agents.
# Browser gets HTML
curl https://api.example.com/
# LLM agent gets token-optimized docs, same URL
curl -H "Accept: text/markdown" https://api.example.com/
# Check token count before downloading
curl -I -H "Accept: text/markdown" https://api.example.com/
# x-markdown-tokens: 1842Content negotiation
Send Accept: text/markdown and GET / returns llms.txt instead of HTML. Agents read the same URL humans visit. Standard HTTP, zero discovery overhead.
Token budgeting
A HEAD request with Accept: text/markdown returns the x-markdown-tokens header with estimated token count. Agents check cost before downloading.
CDN-ready caching
Vary: accept ensures CDNs cache HTML and markdown variants separately. ETags are per-variant. No stale responses, no cache collisions.
Que es llms.txt?
Una convencion emergente que ofrece a los agentes de IA un punto de entrada legible por maquinas a tu documentacion de API, igual que robots.txt lo hizo para los motores de busqueda.
Que es
Un archivo de texto plano en /llms.txt que describe tu API en notacion compacta y eficiente en tokens. Los agentes de IA lo buscan de la misma forma que los navegadores buscan favicon.ico.
Por que importa
Los LLMs desperdician miles de tokens analizando documentacion HTML, la interfaz de Swagger UI y esquemas JSON repetidos. llms.txt les da exactamente lo que necesitan a una fraccion del costo.
Como ayuda SWAGENT
SWAGENT lee tu especificacion OpenAPI y genera automaticamente llms.txt con notacion compacta: tipos en linea, campos obligatorios marcados, abreviaturas de autenticacion. Cero trabajo manual.
Propuesto por llmstxt.org como estandar para contenido web legible por IA.
Documentacion que sirve a todos
llms.txt Para agentes de IA Notacion compacta optimizada en tokens. Resolucion profunda de schemas $ref, allOf, oneOf. Abreviaturas de autenticacion (JWT, KEY, OAuth2). Caching con ETag y cabeceras Cache-Control integrados.
to-humans.md Para desarrolladores Referencia completa en markdown con tabla de contenidos, tablas de parametros, esquemas de respuesta y guias de autenticacion. Lee OpenAPI 2.0 (Swagger) y 3.x, JSON o YAML.
index.html Para descubrimiento Landing page en HTML semantico con tema oscuro, claro o automatico. Cero JavaScript, interacciones solo con CSS. Muestra endpoints, metodos de autenticacion y enlaces a todos los formatos.
Hecho para equipos que lanzan APIs
SaaS AI-first
Expone tu API para consumo de agentes. Agrega llms.txt para que las integraciones de AI descubran y usen tus endpoints con un costo minimo de tokens.
MCP & Tool-use
Construyendo servidores MCP o integraciones de tool-use? SWAGENT genera el esquema compacto que los agentes necesitan para entender tus herramientas al instante.
API Marketplaces
Haz que tu API sea descubrible por agentes de AI que buscan capacidades. llms.txt actua como un escaparate legible por maquinas para tus endpoints.
Developer Experience
Superficie de API extensa? Genera documentacion en markdown, landing pages en HTML y formatos optimizados para AI desde una sola especificacion OpenAPI. Manten todo sincronizado.
Como funciona
Instala el adaptador
npm install @swagent/fastifyRegistra el plugin
import { swagentFastify } from '@swagent/fastify';
app.register(swagentFastify, {
baseUrl: 'https://api.example.com'
});Five routes, content negotiation
GET / → HTML landing page (default)
GET / → llms.txt (Accept: text/markdown)
GET /llms.txt → AI-optimized docs
GET /to-humans.md → Markdown reference
GET /openapi.json → Raw OpenAPI spec
Headers: Vary: accept, ETag (per-variant), x-markdown-tokensComo llms.txt se ve
# Pet Store API
> A sample API for managing pets and orders.
Base: https://api.petstore.io
Docs: [HTML](/) | [OpenAPI JSON](/openapi.json)
## Auth Methods
- JWT: `Authorization: Bearer <token>` via POST /auth/login
- API Key: `X-API-Key: <key>` header
## Conventions
- Auth: JWT = Bearer token, KEY = API Key, NONE = no auth
- `*` after field name = required, all fields string unless noted
- Common errors: 400/401/404 return `{success:false, error}`
---
## Auth
### POST /auth/login - Login | NONE
Body: `{email*, password*}`
200: `{token, expiresIn:number}`
## Pets
### GET /pets - List pets | JWT
Query: ?page:integer ?limit:integer ?species
200: `{data:[{id, name, species, age:number}], total:number}`
### POST /pets - Create pet | JWT
Body: `{name*, species*, age:number, vaccinated:boolean}`
200: `{id, name}`Notacion compacta: * = obligatorio, :type = no string, {...} = objeto. Un LLM lee esto con un costo minimo de tokens y conoce al instante cada endpoint.
Pruébalo tú mismo
Pega una URL de especificación OpenAPI y previsualiza al instante la salida llms.txt generada.
# Tu documentación API aparecerá aquí...
> Ingresa una URL de especificación OpenAPI o pega JSON arriba,
> luego haz clic en Generar para previsualizar la salida llms.txt.Funciona con tu stack
Fastify
Plugin con fastify-plugin. Lee la especificacion de @fastify/swagger automaticamente. Generacion inmediata al iniciar.
npm install @swagent/fastifyExpress
Middleware Router. Pasa tu especificacion OpenAPI, montalo en cualquier ruta. Cache lazy en la primera peticion.
npm install @swagent/expressHono
Instancia de sub-app. Nativo c.html(), c.text(), c.json(). Ligero y rapido.
npm install @swagent/honoElysia
Plugin nativo de Bun para Elysia. Objetos Response nativos con tipos de contenido correctos. Cache lazy en la primera peticion.
bun add @swagent/elysiaKoa
Devuelve una instancia de @koa/router. Monta en cualquier prefijo, cache lazy. Compatible con Koa 2+.
npm install @swagent/koah3 Nitro / Nuxt
Router h3 compatible con Nitro y rutas de servidor Nuxt. Cache lazy, setResponseHeader para tipos de contenido.
npm install @swagent/h3NestJS
Soporte completo para NestJS: SwagentModule.forRoot() con DI o patron setup(). Compatible con NestJS 10+.
npm install @swagent/nestjsCore
Funcion generate() independiente. Usala en cualquier entorno Node.js, funciones serverless o scripts de compilacion.
npm install @swagent/coreCLI
Genera desde cualquier archivo OpenAPI JSON/YAML o URL. Soporta --watch para regeneracion en vivo. Salida a disco.
npx swagent generate ./spec.jsonPreguntas frecuentes
¿Soporta OpenAPI 2.0 (Swagger) y 3.x?
Sí. SWAGENT soporta tanto OpenAPI 2.0 (Swagger) como especificaciones OpenAPI 3.x. El parser maneja los formatos swagger: "2.0" y openapi: "3.x" de forma transparente.
¿Qué pasa cuando mi especificación API cambia?
Las salidas se regeneran automáticamente. Con los adaptadores de framework, la documentación se actualiza al reiniciar el servidor. Con el CLI, vuelve a ejecutar el comando de generación. Sin edición manual necesaria.
¿Qué esquemas de autenticación son compatibles?
Todos los esquemas de seguridad de OpenAPI: Bearer (JWT), API Key (header, query, cookie), OAuth2 (todos los flujos), OpenID Connect y HTTP Basic/Digest. Cada uno se mapea a abreviaturas compactas en llms.txt.
¿Puedo personalizar el tema de la landing page HTML?
La salida HTML es un archivo autocontenido con CSS inline. Puedes sobrescribir los estilos o usar tu propia plantilla. El tema oscuro funciona directamente sin ninguna configuración.
¿Cuál es el impacto en el rendimiento?
Prácticamente nulo. Los adaptadores de framework generan la documentación de forma anticipada al iniciar y cachean el resultado. Las solicitudes posteriores sirven contenido estático. El CLI genera archivos en disco sin costo en tiempo de ejecución.
¿Puedo desactivar salidas individuales?
Sí. Cada adaptador acepta configuración para activar o desactivar salidas específicas (llms.txt, markdown, HTML, OpenAPI JSON). Genera solo lo que necesites.
¿Puedo usar @swagent/core sin un adaptador de framework?
Sí. @swagent/core es un paquete independiente que toma un objeto de especificación OpenAPI y devuelve todas las salidas como strings. Úsalo en cualquier entorno Node.js, funciones serverless o scripts de build.
What is content negotiation and how does SWAGENT use it?
Content negotiation is a standard HTTP mechanism where the client tells the server what format it wants via the Accept header. With SWAGENT, GET / serves HTML by default, but when an LLM agent sends Accept: text/markdown, the same URL returns the llms.txt content. No special paths to discover, agents just read your base URL.
How does token estimation work?
Send a HEAD request with Accept: text/markdown to your root URL. The response includes an x-markdown-tokens header with the estimated token count, powered by estimateTokens from @swagent/core. Agents can check the cost before downloading the full document.
