Документация API
для эпохи агентов
Ваша OpenAPI спецификация, преобразованная в три формата: токен-оптимизированный llms.txt для AI-агентов, полный markdown для разработчиков и семантическая HTML-страница. Одна команда.
$ npm install swagent Ваша документация создана для людей.
А кто её читает сейчас?
LLM-агенты тоже используют документацию вашего API. Swagger UI, Redoc и традиционные доки тратят тысячи токенов на элементы навигации, повторяющиеся схемы и многословное форматирование. Ваши AI-интеграции расплачиваются за это.
{
"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.
Что такое llms.txt?
Новая конвенция, которая предоставляет AI-агентам машиночитаемую точку входа в документацию вашего API, подобно тому, как robots.txt сделал это для поисковых систем.
Что это
Обычный текстовый файл по адресу /llms.txt, описывающий ваш API в компактной, токен-эффективной нотации. AI-агенты ищут его так же, как браузеры ищут favicon.ico.
Почему это важно
LLMs тратят тысячи токенов на парсинг HTML-документации, интерфейса Swagger UI и повторяющихся JSON-схем. llms.txt дает им именно то, что нужно, за долю стоимости.
Как помогает SWAGENT
SWAGENT читает вашу спецификацию OpenAPI и автоматически генерирует llms.txt в компактной нотации: типы inline, обязательные поля отмечены, сокращения авторизации. Ноль ручной работы.
Предложен llmstxt.org как стандарт для AI-читаемого веб-контента.
Документация, которая служит каждому
llms.txt Для AI-агентов Токен-оптимизированная компактная нотация. Глубокое разрешение схем $ref, allOf, oneOf. Сокращения авторизации (JWT, KEY, OAuth2). Встроенное ETag-кэширование и заголовки Cache-Control.
to-humans.md Для разработчиков Полный markdown-справочник с оглавлением, таблицами параметров, схемами ответов и руководствами по аутентификации. Читает OpenAPI 2.0 (Swagger) и 3.x, JSON или YAML.
index.html Для обзора Семантическая HTML-страница с тёмной, светлой или автоматической темой. Без JavaScript, взаимодействие только на CSS. Показывает эндпоинты, методы авторизации и ссылки на все форматы.
Создан для команд, которые выпускают API
AI-first SaaS
Откройте свой API для потребления агентами. Добавьте llms.txt, чтобы AI-интеграции обнаруживали и использовали ваши эндпоинты с минимальными затратами токенов.
MCP & Tool-use
Строите MCP-серверы или Tool-use интеграции? SWAGENT генерирует компактную схему, которая нужна агентам для мгновенного понимания ваших инструментов.
API Marketplaces
Сделайте ваш API обнаруживаемым для AI-агентов, ищущих возможности. llms.txt работает как машиночитаемая витрина для ваших эндпоинтов.
Developer Experience
Большая поверхность API? Генерируйте markdown-документацию, HTML-страницы и AI-оптимизированные форматы из одной OpenAPI спецификации. Держите все синхронизированным.
Как это работает
Установите адаптер
npm install @swagent/fastifyЗарегистрируйте плагин
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-tokensКак это llms.txt выглядит
# 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}`Компактная нотация: * = обязательное, :type = не строка, {...} = объект. LLM читает это с минимальным расходом токенов и сразу знает каждый эндпоинт.
Попробуйте сами
Вставьте URL спецификации OpenAPI и мгновенно просмотрите сгенерированный вывод llms.txt.
# Документация вашего API появится здесь...
> Введите URL спецификации OpenAPI или вставьте JSON выше,
> затем нажмите Сгенерировать для предпросмотра вывода llms.txt.Работает с вашим стеком
Fastify
Плагин на основе fastify-plugin. Автоматически читает спецификацию из @fastify/swagger. Генерация при запуске.
npm install @swagent/fastifyExpress
Middleware-роутер. Передайте OpenAPI спецификацию, монтируйте по любому пути. Ленивое кэширование при первом запросе.
npm install @swagent/expressHono
Экземпляр суб-приложения. Нативные c.html(), c.text(), c.json(). Легковесный и быстрый.
npm install @swagent/honoElysia
Bun-нативный плагин для Elysia. Нативные объекты Response с правильными типами контента. Ленивое кэширование при первом запросе.
bun add @swagent/elysiaKoa
Возвращает экземпляр @koa/router. Монтируйте по любому префиксу, ленивое кэширование. Работает с Koa 2+.
npm install @swagent/koah3 Nitro / Nuxt
h3 роутер, совместимый с Nitro и серверными маршрутами Nuxt. Ленивое кэширование, setResponseHeader для типов контента.
npm install @swagent/h3NestJS
Полная поддержка NestJS: SwagentModule.forRoot() с DI или паттерн setup(). Работает с NestJS 10+.
npm install @swagent/nestjsCore
Автономная функция generate(). Используйте в любой среде Node.js, серверлесс-функциях или скриптах сборки.
npm install @swagent/coreCLI
Генерируйте из любого OpenAPI JSON/YAML файла или URL. Поддерживает --watch для живой регенерации. Вывод на диск.
npx swagent generate ./spec.jsonЧасто задаваемые вопросы
Поддерживает ли он OpenAPI 2.0 (Swagger) и 3.x?
Да. SWAGENT поддерживает спецификации OpenAPI 2.0 (Swagger) и OpenAPI 3.x. Парсер прозрачно обрабатывает форматы swagger: "2.0" и openapi: "3.x".
Что происходит при изменении спецификации API?
Результаты перегенерируются автоматически. С адаптерами фреймворков документация обновляется при перезапуске сервера. С CLI просто перезапустите команду генерации. Ручное редактирование не требуется.
Какие схемы аутентификации поддерживаются?
Все схемы безопасности OpenAPI: Bearer (JWT), API Key (header, query, cookie), OAuth2 (все потоки), OpenID Connect и HTTP Basic/Digest. Каждая маппится в компактные сокращения в llms.txt.
Можно ли настроить тему HTML-страницы?
HTML-вывод представляет собой самодостаточный файл с встроенным CSS. Вы можете переопределить стили или использовать собственный шаблон. Тёмная тема работает из коробки без какой-либо настройки.
Каковы накладные расходы на производительность?
Практически нулевые. Адаптеры фреймворков генерируют документацию при запуске и кэшируют результат. Последующие запросы отдают статический контент. CLI генерирует файлы на диск без затрат во время выполнения.
Можно ли отключить отдельные форматы вывода?
Да. Каждый адаптер принимает конфигурацию для включения или отключения определённых форматов вывода (llms.txt, markdown, HTML, OpenAPI JSON). Генерируйте только то, что вам нужно.
Можно ли использовать @swagent/core без адаптера фреймворка?
Да. @swagent/core это автономный пакет, который принимает объект спецификации OpenAPI и возвращает все результаты в виде строк. Используйте его в любой среде Node.js, серверлесс-функциях или скриптах сборки.
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.