build(api): 提交 OpenAPI 契约快照
固化 A0 基线契约（OpenAPI 3.1，含 ErrorCode/ErrorResponse 与 x-error-codes），供 openapi:diff 做破坏性变更检测。
This commit is contained in:
Stev_Wang committed
1 parent
98a5343e53
commit
63d8889bee
1 file changed
+288
@@ -0,0 +1,288 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"paths": {
|
||||
"/health": {
|
||||
"get": {
|
||||
"description": "真实检查 PostgreSQL 与 Redis；任一不可用返回 503 与统一错误体。",
|
||||
"operationId": "HealthController_check",
|
||||
"parameters": [],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "全部依赖健康",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/HealthResponseDto"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"503": {
|
||||
"description": "依赖不可用（错误码 50002），details 内附各依赖检查结果"
|
||||
}
|
||||
},
|
||||
"summary": "健康检查",
|
||||
"tags": [
|
||||
"platform"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"info": {
|
||||
"title": "灵犀 API",
|
||||
"description": "信息流广告素材生产平台后端 API。\n\n统一约定：\n- 前缀 /api/v1（健康检查 /health 除外）\n- 错误体 { code, message, details, trace_id }\n- 列表响应 { items, next_cursor }",
|
||||
"version": "0.1.0",
|
||||
"contact": {}
|
||||
},
|
||||
"tags": [],
|
||||
"servers": [
|
||||
{
|
||||
"url": "/api/v1",
|
||||
"description": "API v1"
|
||||
}
|
||||
],
|
||||
"components": {
|
||||
"securitySchemes": {
|
||||
"bearer": {
|
||||
"scheme": "bearer",
|
||||
"bearerFormat": "JWT",
|
||||
"type": "http"
|
||||
}
|
||||
},
|
||||
"schemas": {
|
||||
"ComponentHealthDto": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"up",
|
||||
"down"
|
||||
],
|
||||
"example": "up"
|
||||
},
|
||||
"latencyMs": {
|
||||
"type": "number",
|
||||
"description": "检查耗时（毫秒）",
|
||||
"example": 3
|
||||
},
|
||||
"error": {
|
||||
"type": "string",
|
||||
"description": "失败原因（仅 down 时返回）"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"status",
|
||||
"latencyMs"
|
||||
]
|
||||
},
|
||||
"HealthChecksDto": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"database": {
|
||||
"$ref": "#/components/schemas/ComponentHealthDto"
|
||||
},
|
||||
"redis": {
|
||||
"$ref": "#/components/schemas/ComponentHealthDto"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"database",
|
||||
"redis"
|
||||
]
|
||||
},
|
||||
"HealthResponseDto": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"ok",
|
||||
"degraded"
|
||||
],
|
||||
"example": "ok"
|
||||
},
|
||||
"env": {
|
||||
"type": "string",
|
||||
"example": "development"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"example": "0.1.0"
|
||||
},
|
||||
"uptimeSeconds": {
|
||||
"type": "number",
|
||||
"description": "进程运行秒数",
|
||||
"example": 128
|
||||
},
|
||||
"checks": {
|
||||
"$ref": "#/components/schemas/HealthChecksDto"
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"example": "2026-11-02T08:00:00.000Z"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"status",
|
||||
"env",
|
||||
"version",
|
||||
"uptimeSeconds",
|
||||
"checks",
|
||||
"timestamp"
|
||||
]
|
||||
},
|
||||
"ErrorResponseDto": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "number",
|
||||
"description": "错误码（见 ErrorCode 常量）",
|
||||
"example": 42202
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"description": "可直接展示给用户的提示",
|
||||
"example": "内容触发合规拦截"
|
||||
},
|
||||
"details": {
|
||||
"type": "object",
|
||||
"description": "补充信息（字段错误、命中规则等），结构由错误码决定",
|
||||
"example": {
|
||||
"issues": [
|
||||
{
|
||||
"path": "name",
|
||||
"message": "Required"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"trace_id": {
|
||||
"type": "string",
|
||||
"description": "请求追踪 ID，与日志同源",
|
||||
"example": "01JABCDEF0123456789ABCDEFG"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"code",
|
||||
"message",
|
||||
"trace_id"
|
||||
]
|
||||
},
|
||||
"ErrorCode": {
|
||||
"type": "integer",
|
||||
"description": "业务错误码（只允许使用 @lingxi/shared 中登记的错误码）",
|
||||
"enum": [
|
||||
40001,
|
||||
40101,
|
||||
40102,
|
||||
40103,
|
||||
40301,
|
||||
40302,
|
||||
40303,
|
||||
40304,
|
||||
40401,
|
||||
40901,
|
||||
40902,
|
||||
40903,
|
||||
42201,
|
||||
42202,
|
||||
42203,
|
||||
42901,
|
||||
42902,
|
||||
50001,
|
||||
50002,
|
||||
50003
|
||||
]
|
||||
},
|
||||
"ErrorResponse": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"code",
|
||||
"message",
|
||||
"trace_id"
|
||||
],
|
||||
"properties": {
|
||||
"code": {
|
||||
"$ref": "#/components/schemas/ErrorCode"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"details": {
|
||||
"description": "补充信息，结构由错误码决定"
|
||||
},
|
||||
"trace_id": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"x-error-codes": [
|
||||
{
|
||||
"code": 40001
|
||||
},
|
||||
{
|
||||
"code": 40101
|
||||
},
|
||||
{
|
||||
"code": 40102
|
||||
},
|
||||
{
|
||||
"code": 40103
|
||||
},
|
||||
{
|
||||
"code": 40301
|
||||
},
|
||||
{
|
||||
"code": 40302
|
||||
},
|
||||
{
|
||||
"code": 40303
|
||||
},
|
||||
{
|
||||
"code": 40304
|
||||
},
|
||||
{
|
||||
"code": 40401
|
||||
},
|
||||
{
|
||||
"code": 40901
|
||||
},
|
||||
{
|
||||
"code": 40902
|
||||
},
|
||||
{
|
||||
"code": 40903
|
||||
},
|
||||
{
|
||||
"code": 42201
|
||||
},
|
||||
{
|
||||
"code": 42202
|
||||
},
|
||||
{
|
||||
"code": 42203
|
||||
},
|
||||
{
|
||||
"code": 42901
|
||||
},
|
||||
{
|
||||
"code": 42902
|
||||
},
|
||||
{
|
||||
"code": 50001
|
||||
},
|
||||
{
|
||||
"code": 50002
|
||||
},
|
||||
{
|
||||
"code": 50003
|
||||
}
|
||||
],
|
||||
"x-api-config": {
|
||||
"env": "development",
|
||||
"featureVideo": false
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user