API catalog 生成器
只需列出公开 API，即可生成 RFC 9727 要求放在 /.well-known/api-catalog 的 JSON linkset，以及一段通过正确媒体类型提供该文件的 nginx 配置块。
{
"linkset": [
{
"anchor": "https://api.example.com/v1",
"service-desc": [
{
"href": "https://api.example.com/v1/openapi.json",
"type": "application/openapi+json"
}
],
"service-doc": [
{
"href": "https://example.com/docs/api",
"type": "text/html"
}
],
"status": [
{
"href": "https://status.example.com"
}
]
}
]
}
location = /.well-known/api-catalog {
default_type application/linkset+json;
add_header Link '</.well-known/api-catalog>; rel="api-catalog"';
try_files /.well-known/api-catalog =404;
}
将文件上传到 /.well-known/api-catalog，并以 application/linkset+json 提供。nginx 配置块会设置该媒体类型，并添加带有 rel="api-catalog" 的 Link 标头，这是 RFC 9727 对 HEAD 请求的要求。
为什么要发布 API catalog
想调用你的 API 的 agent，首先必须找到它。RFC 9727 于 2025 年 6 月发布，为查找 API 提供了固定入口：知名 URL /.well-known/api-catalog，以及任何页面都可以用来指向该入口的 api-catalog link relation。
catalog 是一个 JSON linkset。每个条目以 API 的基础 URL 为锚点，并链接到机器可读的描述（service-desc，通常是 OpenAPI 文件）、面向用户的文档（service-doc）和状态页。客户端只需读取一个小文件，无须爬取你的文档。
RFC 规定响应必须使用 application/linkset+json，并建议携带 profile https://www.rfc-editor.org/info/rfc9727。目前还没有数据表明哪些 agent 会请求此文件，不过发布它只需要提供一个静态文件。
关于 api-catalog 的常见问题
/.well-known/api-catalog 是什么？
这是 RFC 9727 为机器可读的组织 API 列表定义的位置。该文件是一个 JSON linkset，包含从各个 API 指向其描述、文档和状态页的链接。客户端可以直接从此处获取，也可以通过 api-catalog link relation 找到它。
api-catalog 需要使用什么 Content-Type？
RFC 9727 规定必须使用 application/linkset+json，并建议携带 profile 参数 https://www.rfc-editor.org/info/rfc9727。本页的 nginx 配置块会设置媒体类型和 Link 标头；如果服务器配置允许，请自行添加 profile 参数。
发布 catalog 一定需要 OpenAPI 文件吗？
不需要。使用此生成器时，每个条目只需填写 API 的基础 URL；描述、文档和状态页链接都是可选的。OpenAPI 描述可以让客户端无需阅读文字说明就了解你的端点，因此如果已有 OpenAPI 描述，建议添加。
api-catalog 与 llms.txt 有什么区别？
api-catalog 是一项 IETF RFC，用 JSON 链接列出供软件调用的 API。llms.txt 则是一项提案，用于创建面向阅读文档的语言模型的 Markdown 页面索引。两者用途不同，可以同时发布。