Dokumentasi API
untuk era agen
Spesifikasi OpenAPI Anda, ditransformasi menjadi tiga output: llms.txt yang dioptimalkan token untuk agen AI, markdown lengkap untuk developer, dan halaman landing HTML semantik. Satu perintah.
$ npm install swagent Dokumentasi Anda dibuat untuk manusia.
Siapa yang membacanya sekarang?
Agen LLM juga mengonsumsi dokumentasi API Anda. Swagger UI, Redoc, dan dokumentasi tradisional membuang ribuan token untuk navigasi, schema berulang, dan format yang bertele-tele. Integrasi AI Anda yang menanggung biayanya.
{
"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.
Apa itu llms.txt?
Sebuah konvensi baru yang memberikan agen AI titik masuk yang dapat dibaca mesin ke dokumentasi API Anda, sama seperti robots.txt untuk mesin pencari.
Apa itu
File teks biasa di /llms.txt yang mendeskripsikan API Anda dalam notasi ringkas dan hemat token. Agen AI mencarinya dengan cara yang sama seperti browser mencari favicon.ico.
Mengapa penting
LLMs membuang ribuan token untuk mengurai dokumen HTML, antarmuka Swagger UI, dan skema JSON yang berulang. llms.txt memberikan mereka persis apa yang dibutuhkan dengan biaya yang jauh lebih kecil.
Bagaimana SWAGENT membantu
SWAGENT membaca spesifikasi OpenAPI Anda dan secara otomatis menghasilkan llms.txt dengan notasi ringkas: tipe inline, field wajib ditandai, singkatan autentikasi. Tanpa kerja manual.
Diusulkan oleh llmstxt.org sebagai standar untuk konten web yang dapat dibaca AI.
Dokumentasi yang melayani semua
llms.txt Untuk agen AI Notasi ringkas yang dioptimalkan token. Resolusi mendalam schema $ref, allOf, oneOf. Singkatan autentikasi (JWT, KEY, OAuth2). Caching ETag dan header Cache-Control bawaan.
to-humans.md Untuk developer Referensi markdown lengkap dengan daftar isi, tabel parameter, schema respons, dan panduan autentikasi. Membaca OpenAPI 2.0 (Swagger) dan 3.x, JSON atau YAML.
index.html Untuk penemuan Halaman landing HTML semantik dengan tema gelap, terang, atau otomatis. Tanpa JavaScript, interaksi hanya CSS. Menampilkan endpoint, metode autentikasi, dan tautan ke semua format.
Dibuat untuk tim yang merilis API
SaaS AI-first
Ekspos API Anda untuk konsumsi agen. Tambahkan llms.txt agar integrasi AI menemukan dan menggunakan endpoint Anda dengan biaya token minimal.
MCP & Tool-use
Membangun server MCP atau integrasi tool-use? SWAGENT menghasilkan schema ringkas yang dibutuhkan agen untuk memahami tool Anda secara instan.
API Marketplaces
Buat API Anda dapat ditemukan oleh agen AI yang mencari kapabilitas. llms.txt bertindak sebagai etalase yang dapat dibaca mesin untuk endpoint Anda.
Developer Experience
Permukaan API yang luas? Hasilkan dokumentasi markdown, halaman landing HTML, dan format yang dioptimalkan untuk AI dari satu spesifikasi OpenAPI. Jaga semuanya tetap sinkron.
Cara kerjanya
Instal adapter
npm install @swagent/fastifyDaftarkan 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-tokensSeperti apa llms.txt tampilannya
# 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}`Notasi ringkas: * = wajib, :type = bukan string, {...} = objek. LLM membaca ini dengan biaya token minimal dan langsung mengetahui setiap endpoint.
Coba sendiri
Tempel URL spesifikasi OpenAPI dan pratinjau langsung output llms.txt yang dihasilkan.
# Dokumentasi API Anda akan muncul di sini...
> Masukkan URL spesifikasi OpenAPI atau tempel JSON di atas,
> lalu klik Hasilkan untuk pratinjau output llms.txt.Bekerja dengan stack Anda
Fastify
Plugin dengan fastify-plugin. Membaca spesifikasi dari @fastify/swagger secara otomatis. Generasi langsung saat startup.
npm install @swagent/fastifyExpress
Middleware Router. Berikan spesifikasi OpenAPI Anda, pasang di path mana pun. Caching lazy pada permintaan pertama.
npm install @swagent/expressHono
Instance sub-app. Native c.html(), c.text(), c.json(). Ringan dan cepat.
npm install @swagent/honoElysia
Plugin Bun-native untuk Elysia. Objek Response native dengan tipe konten yang benar. Caching lazy pada permintaan pertama.
bun add @swagent/elysiaKoa
Mengembalikan instance @koa/router. Pasang di prefix mana pun, caching lazy. Kompatibel dengan Koa 2+.
npm install @swagent/koah3 Nitro / Nuxt
Router h3 yang kompatibel dengan Nitro dan rute server Nuxt. Caching lazy, setResponseHeader untuk tipe konten.
npm install @swagent/h3NestJS
Dukungan penuh NestJS: SwagentModule.forRoot() dengan DI atau pola setup(). Kompatibel dengan NestJS 10+.
npm install @swagent/nestjsCore
Fungsi generate() mandiri. Gunakan di lingkungan Node.js apa pun, fungsi serverless, atau skrip build.
npm install @swagent/coreCLI
Hasilkan dari file OpenAPI JSON/YAML atau URL apa pun. Mendukung --watch untuk regenerasi langsung. Output ke disk.
npx swagent generate ./spec.jsonPertanyaan yang sering diajukan
Apakah mendukung OpenAPI 2.0 (Swagger) dan 3.x?
Ya. SWAGENT mendukung spesifikasi OpenAPI 2.0 (Swagger) dan OpenAPI 3.x. Parser menangani format swagger: "2.0" dan openapi: "3.x" secara transparan.
Apa yang terjadi ketika spesifikasi API saya berubah?
Output diregenerasi secara otomatis. Dengan adapter framework, dokumentasi diperbarui saat server restart. Dengan CLI, jalankan ulang perintah generate. Tidak perlu pengeditan manual.
Skema autentikasi apa saja yang didukung?
Semua skema keamanan OpenAPI: Bearer (JWT), API Key (header, query, cookie), OAuth2 (semua flow), OpenID Connect, dan HTTP Basic/Digest. Masing-masing dipetakan ke singkatan ringkas dalam llms.txt.
Bisakah saya menyesuaikan tema halaman landing HTML?
Output HTML adalah file mandiri dengan CSS inline. Anda bisa menimpa gaya atau menggunakan template sendiri. Tema gelap langsung berfungsi tanpa konfigurasi.
Berapa overhead performanya?
Hampir nol. Adapter framework menghasilkan dokumentasi saat startup dan meng-cache hasilnya. Permintaan berikutnya menyajikan konten statis. CLI menghasilkan file ke disk tanpa biaya runtime.
Bisakah saya menonaktifkan output individual?
Ya. Setiap adapter menerima konfigurasi untuk mengaktifkan atau menonaktifkan output tertentu (llms.txt, markdown, HTML, OpenAPI JSON). Hasilkan hanya yang Anda butuhkan.
Bisakah saya menggunakan @swagent/core tanpa adapter framework?
Ya. @swagent/core adalah paket mandiri yang menerima objek spesifikasi OpenAPI dan mengembalikan semua output sebagai string. Gunakan di lingkungan Node.js apa pun, fungsi serverless, atau skrip 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.