API-dokumentation
för Agent-eran
Din OpenAPI-spec, omvandlad till tre utdata: token-optimerad llms.txt för AI-agenter, fullständig markdown för utvecklare och en semantisk HTML-landningssida. Ett kommando.
$ npm install swagent Din dokumentation är byggd för människor.
Vem läser den nu?
LLM-agenter konsumerar också din API-dokumentation. Swagger UI, Redoc och traditionell dokumentation slösar tusentals tokens på navigeringselement, upprepade scheman och omständlig formatering. Dina AI-drivna integrationer betalar priset.
{
"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.
Vad ar llms.txt?
En framvaxande konvention som ger AI-agenter en maskinlasbar ingangspunkt till din API-dokumentation, precis som robots.txt gjorde for sokmotorer.
Vad det ar
En ren textfil pa /llms.txt som beskriver ditt API i kompakt, token-effektiv notation. AI-agenter soker efter den pa samma satt som webblasare soker efter favicon.ico.
Varfor det ar viktigt
LLMs slosar tusentals tokens pa att tolka HTML-dokumentation, Swagger UI-granssnittet och upprepade JSON-scheman. llms.txt ger dem exakt vad de behover till en brakdel av kostnaden.
Hur SWAGENT hjalper
SWAGENT laser din OpenAPI-specifikation och genererar automatiskt llms.txt med kompakt notation: typer inline, obligatoriska falt markerade, autentiseringsfortkortningar. Noll manuellt arbete.
Foreslagit av llmstxt.org som standard for AI-lasbart webbinnehall.
Dokumentation som tjänar alla
llms.txt För AI-agenter Token-optimerad kompakt notation. Djup upplösning av $ref-, allOf-, oneOf-scheman. Autentiseringsförkortningar (JWT, KEY, OAuth2). Inbyggd ETag-caching och Cache-Control-headers.
to-humans.md För utvecklare Fullständig markdown-referens med innehållsförteckning, parametertabeller, svarsscheman och autentiseringsguider. Läser OpenAPI 2.0 (Swagger) och 3.x, JSON eller YAML.
index.html För upptäckt Semantisk HTML-landningssida med mörkt, ljust eller automatiskt tema. Noll JavaScript, enbart CSS-interaktioner. Visar endpoints, autentiseringsmetoder och länkar till alla format.
Byggt for team som levererar APIs
AI-first SaaS
Exponera ditt API for agentkonsumtion. Lagg till llms.txt sa att AI-integrationer upptacker och anvander dina endpoints med minimal tokenkostnad.
MCP & Tool-use
Bygger du MCP-servrar eller Tool-use-integrationer? SWAGENT genererar det kompakta schema som agenter behover for att forsta dina verktyg omedelbart.
API Marketplaces
Gor ditt API upptackbart av AI-agenter som soker efter funktioner. llms.txt fungerar som ett maskinlasbart skyltfonster for dina endpoints.
Developer Experience
Stort API-yta? Generera markdown-dokumentation, HTML-landningssidor och AI-optimerade format fran en enda OpenAPI-spec. Hall allt synkroniserat.
Hur det fungerar
Installera adaptern
npm install @swagent/fastifyRegistrera pluginet
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-tokensHur det llms.txt ser ut
# 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}`Kompakt notation: * = obligatorisk, :type = icke-string, {...} = object. En LLM läser detta med minimal tokenkostnad och känner omedelbart till varje endpoint.
Testa själv
Klistra in en OpenAPI-specifikations-URL och förhandsgranska den genererade llms.txt-utdatan direkt.
# Din API-dokumentation visas här...
> Ange en OpenAPI-specifikations-URL eller klistra in JSON ovan,
> klicka sedan på Generera för att förhandsgranska llms.txt-utdatan.Fungerar med din stack
Fastify
Plugin med fastify-plugin. Läser spec från @fastify/swagger automatiskt. Generering vid uppstart.
npm install @swagent/fastifyExpress
Router middleware. Skicka din OpenAPI-spec, montera på valfri sökväg. Lazy caching vid första förfrågan.
npm install @swagent/expressHono
Sub-app-instans. Nativ c.html(), c.text(), c.json(). Lättviktig och snabb.
npm install @swagent/honoElysia
Bun-nativt plugin for Elysia. Nativa Response-objekt med korrekta content types. Lazy caching vid forsta forfragen.
bun add @swagent/elysiaKoa
Returnerar en @koa/router-instans. Montera pa valfritt prefix, lazy caching. Fungerar med Koa 2+.
npm install @swagent/koah3 Nitro / Nuxt
h3-router kompatibel med Nitro och Nuxt-serverrutter. Lazy caching, setResponseHeader for content types.
npm install @swagent/h3NestJS
Fullt NestJS-stod: SwagentModule.forRoot() med DI eller setup()-monster. Fungerar med NestJS 10+.
npm install @swagent/nestjsCore
Fristaende generate()-funktion. Anvand i vilken Node.js-miljo som helst, serverlosa funktioner eller byggskript.
npm install @swagent/coreCLI
Generera fran valfri OpenAPI JSON/YAML-fil eller URL. Stodjer --watch for live-regenerering. Utdata till disk.
npx swagent generate ./spec.jsonVanliga fragor
Stods OpenAPI 2.0 (Swagger) och 3.x?
Ja. SWAGENT stoder bade OpenAPI 2.0 (Swagger) och OpenAPI 3.x-specifikationer. Parsern hanterar formaten swagger: "2.0" och openapi: "3.x" transparent.
Vad hander nar min API-specifikation andras?
Utdata atergenereras automatiskt. Med framework-adaptrar uppdateras dokumentationen vid omstart av servern. Med CLI, kor genereringskommandot igen. Ingen manuell redigering behovs.
Vilka autentiseringsscheman stods?
Alla OpenAPI-sakerhetsscheman: Bearer (JWT), API Key (header, query, cookie), OAuth2 (alla flodar), OpenID Connect och HTTP Basic/Digest. Varje schema mappas till kompakta fortkortningar i llms.txt.
Kan jag anpassa temat for HTML-landningssidan?
HTML-utdata ar en friestaende fil med inline CSS. Du kan overskriva stilar eller anvanda din egen mall. Det morka temat fungerar direkt utan nagon konfiguration.
Hur stor ar prestandapoverkan?
Nastan noll. Framework-adaptrar genererar dokumentation vid uppstart och cachar resultatet. Efterfoljande forfragan serverar statiskt innehall. CLI genererar filer till disk utan korningskostnad.
Kan jag inaktivera enskilda utdata?
Ja. Varje adapter accepterar konfiguration for att aktivera eller inaktivera specifika utdata (llms.txt, markdown, HTML, OpenAPI JSON). Generera bara det du behover.
Kan jag anvanda @swagent/core utan en framework-adapter?
Ja. @swagent/core ar ett friestaende paket som tar ett OpenAPI-spec-objekt och returnerar alla utdata som strangar. Anvand det i vilken Node.js-miljo som helst, serverlosa funktioner eller build-skript.
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.