V2
OpenAPI
使用公开的 OpenAPI 文档和元数据接口生成工具链或做自动化校验。
OpenAPI
适用范围
本页说明公开的 OpenAPI 文档入口，以及用于缓存和自动化校验的元数据接口。它们适合接代码生成、SDK 生成、CI 校验和接口变更检测。
核心定义
| 接口 | 作用 |
|---|---|
GET /v2/openapi.json | 返回完整的 OpenAPI 文档。 |
GET /v2/openapi/meta | 返回 OpenAPI 文档的元数据。 |
字段说明或规则
/v2/openapi.json
这个接口返回机器可读的 OpenAPI 规范，适合做：
- SDK 生成
- 请求校验
- 文档同步
- 自动化测试
它是公共路由，不需要 Authorization 头。
/v2/openapi/meta
这个接口返回轻量元数据，适合做缓存判断和变更检测。
{
"etag": "sha256_of_spec",
"generatedAt": "2026-04-01T08:00:00.000Z",
"pathCount": 15,
"schemaCount": 80
}| 字段 | 说明 |
|---|---|
etag | OpenAPI 文档序列化后计算出的摘要值，用于判断内容是否变化。 |
generatedAt | 这份 OpenAPI 元数据对应的生成时间或版本时间，使用 ISO 8601 表示。 |
pathCount | 当前 spec 中 paths 的数量。 |
schemaCount | 当前 spec 中 components.schemas 的数量。 |
使用建议
- 先拉取
meta，再决定是否下载完整openapi.json - 在 CI 里可以用
etag或generatedAt发现本地缓存是否需要刷新 - 生成客户端时优先使用
openapi.json，不要从页面正文反向解析接口
常见注意事项
/v2/openapi.json和/v2/openapi/meta都是公共路由，不需要 token。meta只适合做轻量判断，不包含完整 schema。- 如果 spec 来源发生变化，
etag和generatedAt也会跟着变化。