เอกสาร API
สำหรับ ยุค Agent
OpenAPI spec ของคุณ แปลงเป็นสามเอาต์พุต: llms.txt ที่ปรับให้ประหยัดโทเค็นสำหรับ AI agent, markdown ฉบับเต็มสำหรับนักพัฒนา และหน้า HTML เชิงความหมาย คำสั่งเดียว
$ npm install swagent เอกสารของคุณสร้างมาสำหรับมนุษย์
แล้วใครอ่านตอนนี้?
LLM agent ก็ใช้เอกสาร 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 agent มีจุดเข้าถึงเอกสาร API ของคุณที่เครื่องอ่านได้ เหมือนกับที่ robots.txt ทำเพื่อเครื่องมือค้นหา
คืออะไร
ไฟล์ข้อความธรรมดาที่ /llms.txt ที่อธิบาย API ของคุณในรูปแบบกระชับและประหยัด token AI agent ค้นหาไฟล์นี้เหมือนกับที่เบราว์เซอร์ค้นหา favicon.ico
ทำไมจึงสำคัญ
LLMs สิ้นเปลืองโทเค็นหลายพันตัวในการแยกวิเคราะห์เอกสาร HTML, อินเทอร์เฟซ Swagger UI และ JSON schema ที่ซ้ำกัน llms.txt ให้ข้อมูลที่ต้องการอย่างแม่นยำด้วยต้นทุนเพียงเศษเสี้ยว
SWAGENT ช่วยอย่างไร
SWAGENT อ่านสเปค OpenAPI ของคุณและสร้าง llms.txt โดยอัตโนมัติด้วยรูปแบบกระชับ: ประเภทข้อมูลแบบ inline, ฟิลด์บังคับถูกทำเครื่องหมาย, ตัวย่อการยืนยันตัวตน ไม่ต้องทำงานด้วยมือ
เสนอโดย llmstxt.org เป็นมาตรฐานสำหรับเนื้อหาเว็บที่ AI อ่านได้
เอกสารที่ตอบโจทย์ ทุกคน
llms.txt สำหรับ AI Agent รูปแบบกะทัดรัดที่ปรับให้ประหยัดโทเค็น การแก้ไข schema เชิงลึกสำหรับ $ref, allOf, oneOf ตัวย่อการยืนยันตัวตน (JWT, KEY, OAuth2) แคช ETag และ header Cache-Control ในตัว
to-humans.md สำหรับนักพัฒนา เอกสารอ้างอิง markdown ฉบับเต็ม พร้อมสารบัญ ตารางพารามิเตอร์ สคีมาการตอบกลับ และคู่มือการยืนยันตัวตน อ่าน OpenAPI 2.0 (Swagger) และ 3.x, JSON หรือ YAML
index.html สำหรับการค้นพบ หน้า HTML เชิงความหมายพร้อมธีมมืด สว่าง หรืออัตโนมัติ ไม่ใช้ JavaScript ใช้เฉพาะ CSS แสดง endpoint วิธีการยืนยันตัวตน และลิงก์ไปยังทุกรูปแบบ
สร้างสำหรับทีมที่ เปิดตัว API
SaaS ที่เน้น AI
เปิด API ของคุณให้ agent ใช้งาน เพิ่ม llms.txt เพื่อให้การเชื่อมต่อ AI ค้นพบและใช้ endpoint ของคุณด้วยต้นทุนโทเค็นน้อยที่สุด
MCP & Tool-use
กำลังสร้าง MCP server หรือการเชื่อมต่อ Tool-use? SWAGENT สร้าง schema กะทัดรัดที่ agent ต้องการเพื่อเข้าใจเครื่องมือของคุณทันที
API Marketplaces
ทำให้ API ของคุณถูกค้นพบโดย AI agent ที่ค้นหาความสามารถ llms.txt ทำหน้าที่เป็นหน้าร้านที่เครื่องอ่านได้สำหรับ endpoint ของคุณ
Developer Experience
API ขนาดใหญ่? สร้างเอกสาร markdown, หน้า HTML และรูปแบบที่ปรับให้เหมาะกับ AI จาก OpenAPI spec เดียว รักษาทุกอย่างให้ซิงค์กัน
วิธี การทำงาน
ติดตั้ง adapter
npm install @swagent/fastifyลงทะเบียน 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-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 = ไม่ใช่ string, {...} = object LLM อ่านข้อมูลนี้ด้วยต้นทุนโทเค็นน้อยที่สุดและรู้จักทุก endpoint ทันที
ลองด้วย ตัวเอง
วาง URL ข้อกำหนด OpenAPI และดูตัวอย่างผลลัพธ์ llms.txt ที่สร้างขึ้นทันที
# เอกสาร API ของคุณจะปรากฏที่นี่...
> ป้อน URL ข้อกำหนด OpenAPI หรือวาง JSON ด้านบน
> จากนั้นคลิกสร้างเพื่อดูตัวอย่างผลลัพธ์ llms.txtใช้งานกับ stack ของคุณ
Fastify
Plugin ด้วย fastify-plugin อ่าน spec จาก @fastify/swagger อัตโนมัติ สร้างเอกสารทันทีตอนเริ่มต้น
npm install @swagent/fastifyExpress
Router middleware ส่ง OpenAPI spec ของคุณ ติดตั้งที่ path ใดก็ได้ แคชแบบ lazy ที่คำขอแรก
npm install @swagent/expressHono
Sub-app instance ใช้ c.html(), c.text(), c.json() แบบเนทีฟ เบาและเร็ว
npm install @swagent/honoElysia
ปลั๊กอิน Bun-native สำหรับ Elysia ออบเจกต์ Response แบบเนทีฟพร้อม content type ที่ถูกต้อง แคชแบบ lazy ที่คำขอแรก
bun add @swagent/elysiaKoa
คืน instance ของ @koa/router ติดตั้งที่ prefix ใดก็ได้ แคชแบบ lazy ใช้งานกับ Koa 2+
npm install @swagent/koah3 Nitro / Nuxt
Router h3 ที่เข้ากันได้กับ Nitro และ Nuxt server routes แคชแบบ lazy ใช้ setResponseHeader สำหรับ content type
npm install @swagent/h3NestJS
รองรับ NestJS เต็มรูปแบบ: SwagentModule.forRoot() พร้อม DI หรือแพทเทิร์น setup() ใช้งานกับ NestJS 10+
npm install @swagent/nestjsCore
ฟังก์ชัน generate() แบบสแตนด์อโลน ใช้ในสภาพแวดล้อม Node.js ใดก็ได้ ฟังก์ชัน serverless หรือ build script
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 ของฉันเปลี่ยนแปลง?
เอาต์พุตจะถูกสร้างใหม่โดยอัตโนมัติ สำหรับ adapter framework เอกสารจะอัปเดตเมื่อรีสตาร์ทเซิร์ฟเวอร์ สำหรับ CLI ให้รันคำสั่ง generate อีกครั้ง ไม่ต้องแก้ไขด้วยตนเอง
รองรับรูปแบบการยืนยันตัวตนใดบ้าง?
รูปแบบความปลอดภัย OpenAPI ทั้งหมด: Bearer (JWT), API Key (header, query, cookie), OAuth2 (ทุก flow), OpenID Connect และ HTTP Basic/Digest แต่ละรูปแบบจะถูกแมปเป็นตัวย่อกะทัดรัดใน llms.txt
สามารถปรับแต่งธีมหน้า landing HTML ได้หรือไม่?
เอาต์พุต HTML เป็นไฟล์เดียวที่มี CSS inline คุณสามารถเขียนทับสไตล์หรือใช้เทมเพลตของคุณเอง ธีมมืดใช้งานได้ทันทีโดยไม่ต้องกำหนดค่า
มีผลกระทบต่อประสิทธิภาพมากแค่ไหน?
แทบไม่มี Adapter framework สร้างเอกสารทันทีตอนเริ่มต้นและแคชผลลัพธ์ คำขอถัดไปให้บริการเนื้อหาแบบ static CLI สร้างไฟล์ลงดิสก์โดยไม่มีค่าใช้จ่ายขณะรันไทม์
สามารถปิดเอาต์พุตแต่ละรายการได้หรือไม่?
ได้ แต่ละ adapter รับการกำหนดค่าเพื่อเปิดหรือปิดเอาต์พุตเฉพาะ (llms.txt, markdown, HTML, OpenAPI JSON) สร้างเฉพาะสิ่งที่คุณต้องการ
สามารถใช้ @swagent/core โดยไม่มี adapter framework ได้หรือไม่?
ได้ @swagent/core เป็นแพ็กเกจอิสระที่รับอ็อบเจกต์ข้อกำหนด OpenAPI และส่งคืนเอาต์พุตทั้งหมดเป็น string ใช้ได้ในทุกสภาพแวดล้อม Node.js, ฟังก์ชัน serverless หรือ build script
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.