APIドキュメント
のための エージェント時代
OpenAPI仕様を3つの出力に変換：AIエージェント向けにトークン最適化されたllms.txt、開発者向けの完全なmarkdown、セマンティックHTMLランディングページ。コマンド1つで完了。
$ 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とは？
robots.txtが検索エンジンに対して行ったように、AIエージェントにAPI ドキュメントへの機械可読なエントリーポイントを提供する新しい規約です。
llms.txtとは
/llms.txt に配置されるプレーンテキストファイルで、コンパクトでトークン効率の良い記法でAPIを記述します。AIエージェントがこれを探す方法は、ブラウザが favicon.ico を探すのと同じです。
なぜ重要か
LLMsはHTMLドキュメント、Swagger UIのインターフェース、繰り返されるJSONスキーマの解析に数千トークンを浪費しています。llms.txtは必要な情報をごくわずかなコストで提供します。
SWAGENTの役割
SWAGENTはOpenAPI仕様を読み取り、コンパクトな記法でllms.txtを自動生成します：型はインライン、必須フィールドはマーク済み、認証は略記。手作業ゼロ。
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 ファースト SaaS
APIをエージェントに公開しましょう。llms.txtを追加すれば、AI統合が最小限のトークンコストでエンドポイントを発見・利用できます。
MCP & Tool-use
MCPサーバーやTool-use統合を構築中ですか？SWAGENTはエージェントがツールを即座に理解するために必要なコンパクトなスキーマを生成します。
API Marketplaces
機能を探すAIエージェントにAPIを発見可能にしましょう。llms.txtはエンドポイントの機械可読なショーケースとして機能します。
Developer Experience
API の規模が大きい？1つのOpenAPI仕様からmarkdownドキュメント、HTMLランディングページ、AI最適化フォーマットを生成。すべてを同期して管理。
使い方 は簡単
アダプターをインストール
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は最小限のトークンコストでこれを読み取り、すべてのエンドポイントを即座に把握します。
自分で 試してみる
OpenAPI仕様のURLを貼り付けて、生成されたllms.txt出力を即座にプレビューできます。
# APIドキュメントがここに表示されます...
> 上にOpenAPI仕様のURLを入力するかJSONを貼り付けて、
> 生成をクリックしてllms.txt出力をプレビューしてください。あなたの スタックに対応
Fastify
fastify-pluginによるプラグイン。@fastify/swaggerから仕様を自動読み取り。起動時に即座に生成。
npm install @swagent/fastifyExpress
Routerミドルウェア。OpenAPI仕様を渡して任意のパスにマウント。初回リクエスト時に遅延キャッシュ。
npm install @swagent/expressHono
サブアプリインスタンス。ネイティブのc.html()、c.text()、c.json()。軽量で高速。
npm install @swagent/honoElysia
Elysia用のBunネイティブプラグイン。適切なコンテンツタイプのネイティブResponseオブジェクト。初回リクエスト時に遅延キャッシュ。
bun add @swagent/elysiaKoa
@koa/routerインスタンスを返します。任意のプレフィックスにマウント、遅延キャッシュ。Koa 2+対応。
npm install @swagent/koah3 Nitro / Nuxt
NitroおよびNuxtサーバールートと互換性のあるh3ルーター。遅延キャッシュ、コンテンツタイプ用のsetResponseHeader。
npm install @swagent/h3NestJS
NestJSの完全サポート：DIを使ったSwagentModule.forRoot()または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 の場合は generate コマンドを再実行してください。手動編集は不要です。
どの認証スキームに対応していますか？
すべての 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.