mirror of
https://github.com/EZ-Api/ez-api.git
synced 2026-01-13 17:47:51 +00:00
feat(api): add public status endpoints with version injection
Replace health_handler with status_handler providing public /status and /about endpoints. Add build-time version injection via ldflags in Makefile, and support --version/-v CLI flag. - Add /status endpoint returning runtime status, uptime, and version - Add /about endpoint with system metadata (name, description, repo) - Configure VERSION variable with git describe fallback - Update swagger docs and api.md for new public endpoints - Remove deprecated /api/status/test endpoint
This commit is contained in:
zenfun
10
docs/api.md
10
docs/api.md
@@ -128,8 +128,14 @@ graph TD
|
||||
|
||||
## 4. API 模块概览
|
||||
|
||||
### 4.0 公开接口 (Auth API) - 无需中间件
|
||||
- **身份识别**：`GET /auth/whoami` - 根据 Token 返回身份类型和详细信息。
|
||||
### 4.0 公开接口 - 无需鉴权
|
||||
| 端点 | 说明 | 响应示例 |
|
||||
|------|------|----------|
|
||||
| `GET /health` | 健康检查（含依赖状态） | `{"status": "ok", "database": "up", "redis": "up", "uptime": "1h30m"}` |
|
||||
| `GET /status` | 公开状态摘要 | `{"status": "ok", "uptime": "1h30m", "version": "v0.1.0"}` |
|
||||
| `GET /about` | 系统信息 | `{"name": "EZ-API Gateway", "version": "v0.1.0", ...}` |
|
||||
| `GET /auth/whoami` | 身份识别 | 根据 Token 返回身份类型和详细信息 |
|
||||
| `GET /swagger/*` | API 文档 | Swagger UI |
|
||||
|
||||
### 4.1 管理端 (Admin API) - 需 Admin Token
|
||||
- **租户管理**：创建 Master、签发子 Key、实时 QPS 监控、冻结/解冻。
|
||||
|
||||
121
docs/docs.go
121
docs/docs.go
@@ -24,6 +24,26 @@ const docTemplate = `{
|
||||
"host": "{{.Host}}",
|
||||
"basePath": "{{.BasePath}}",
|
||||
"paths": {
|
||||
"/about": {
|
||||
"get": {
|
||||
"description": "Returns system metadata for display on an about page",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Public"
|
||||
],
|
||||
"summary": "Get system information",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.AboutResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/admin/api-keys": {
|
||||
"get": {
|
||||
"security": [
|
||||
@@ -2844,32 +2864,6 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/status/test": {
|
||||
"get": {
|
||||
"description": "Checks Redis/PostgreSQL connections and reports status",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"system"
|
||||
],
|
||||
"summary": "Test dependency connectivity",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.HealthStatus"
|
||||
}
|
||||
},
|
||||
"503": {
|
||||
"description": "Service Unavailable",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.HealthStatus"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/auth/whoami": {
|
||||
"get": {
|
||||
"security": [
|
||||
@@ -2990,6 +2984,26 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"/status": {
|
||||
"get": {
|
||||
"description": "Returns public runtime status information without sensitive data",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Public"
|
||||
],
|
||||
"summary": "Get system status",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.StatusResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v1/logs": {
|
||||
"get": {
|
||||
"security": [
|
||||
@@ -3925,23 +3939,6 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"github_com_ez-api_ez-api_internal_service.HealthStatus": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"database": {
|
||||
"type": "string"
|
||||
},
|
||||
"redis": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"uptime": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"github_com_ez-api_ez-api_internal_service.LogWebhookConfig": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4049,6 +4046,27 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.AboutResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"description": {
|
||||
"type": "string",
|
||||
"example": "High-performance LLM API gateway"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"example": "EZ-API Gateway"
|
||||
},
|
||||
"repository": {
|
||||
"type": "string",
|
||||
"example": "https://github.com/ez-api/ez-api"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"example": "0.1.0"
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.AccessResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4635,6 +4653,23 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.StatusResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"example": "ok"
|
||||
},
|
||||
"uptime": {
|
||||
"type": "string",
|
||||
"example": "72h30m15s"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"example": "0.1.0"
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.TokenView": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
@@ -18,6 +18,26 @@
|
||||
"host": "localhost:8080",
|
||||
"basePath": "/",
|
||||
"paths": {
|
||||
"/about": {
|
||||
"get": {
|
||||
"description": "Returns system metadata for display on an about page",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Public"
|
||||
],
|
||||
"summary": "Get system information",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.AboutResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/admin/api-keys": {
|
||||
"get": {
|
||||
"security": [
|
||||
@@ -2838,32 +2858,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/status/test": {
|
||||
"get": {
|
||||
"description": "Checks Redis/PostgreSQL connections and reports status",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"system"
|
||||
],
|
||||
"summary": "Test dependency connectivity",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.HealthStatus"
|
||||
}
|
||||
},
|
||||
"503": {
|
||||
"description": "Service Unavailable",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/github_com_ez-api_ez-api_internal_service.HealthStatus"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/auth/whoami": {
|
||||
"get": {
|
||||
"security": [
|
||||
@@ -2984,6 +2978,26 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/status": {
|
||||
"get": {
|
||||
"description": "Returns public runtime status information without sensitive data",
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Public"
|
||||
],
|
||||
"summary": "Get system status",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/internal_api.StatusResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v1/logs": {
|
||||
"get": {
|
||||
"security": [
|
||||
@@ -3919,23 +3933,6 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"github_com_ez-api_ez-api_internal_service.HealthStatus": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"database": {
|
||||
"type": "string"
|
||||
},
|
||||
"redis": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"uptime": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"github_com_ez-api_ez-api_internal_service.LogWebhookConfig": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4043,6 +4040,27 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.AboutResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"description": {
|
||||
"type": "string",
|
||||
"example": "High-performance LLM API gateway"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"example": "EZ-API Gateway"
|
||||
},
|
||||
"repository": {
|
||||
"type": "string",
|
||||
"example": "https://github.com/ez-api/ez-api"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"example": "0.1.0"
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.AccessResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4629,6 +4647,23 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.StatusResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"example": "ok"
|
||||
},
|
||||
"uptime": {
|
||||
"type": "string",
|
||||
"example": "72h30m15s"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"example": "0.1.0"
|
||||
}
|
||||
}
|
||||
},
|
||||
"internal_api.TokenView": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
@@ -247,17 +247,6 @@ definitions:
|
||||
updatedAt:
|
||||
type: string
|
||||
type: object
|
||||
github_com_ez-api_ez-api_internal_service.HealthStatus:
|
||||
properties:
|
||||
database:
|
||||
type: string
|
||||
redis:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
uptime:
|
||||
type: string
|
||||
type: object
|
||||
github_com_ez-api_ez-api_internal_service.LogWebhookConfig:
|
||||
properties:
|
||||
cooldown_seconds:
|
||||
@@ -328,6 +317,21 @@ definitions:
|
||||
description: Valid is true if Time is not NULL
|
||||
type: boolean
|
||||
type: object
|
||||
internal_api.AboutResponse:
|
||||
properties:
|
||||
description:
|
||||
example: High-performance LLM API gateway
|
||||
type: string
|
||||
name:
|
||||
example: EZ-API Gateway
|
||||
type: string
|
||||
repository:
|
||||
example: https://github.com/ez-api/ez-api
|
||||
type: string
|
||||
version:
|
||||
example: 0.1.0
|
||||
type: string
|
||||
type: object
|
||||
internal_api.AccessResponse:
|
||||
properties:
|
||||
default_namespace:
|
||||
@@ -712,6 +716,18 @@ definitions:
|
||||
tokens:
|
||||
type: integer
|
||||
type: object
|
||||
internal_api.StatusResponse:
|
||||
properties:
|
||||
status:
|
||||
example: ok
|
||||
type: string
|
||||
uptime:
|
||||
example: 72h30m15s
|
||||
type: string
|
||||
version:
|
||||
example: 0.1.0
|
||||
type: string
|
||||
type: object
|
||||
internal_api.TokenView:
|
||||
properties:
|
||||
allow_ips:
|
||||
@@ -943,6 +959,19 @@ info:
|
||||
title: EZ-API Control Plane
|
||||
version: 0.0.1
|
||||
paths:
|
||||
/about:
|
||||
get:
|
||||
description: Returns system metadata for display on an about page
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/internal_api.AboutResponse'
|
||||
summary: Get system information
|
||||
tags:
|
||||
- Public
|
||||
/admin/api-keys:
|
||||
get:
|
||||
description: List API keys
|
||||
@@ -2744,23 +2773,6 @@ paths:
|
||||
summary: Force sync snapshot
|
||||
tags:
|
||||
- admin
|
||||
/api/status/test:
|
||||
get:
|
||||
description: Checks Redis/PostgreSQL connections and reports status
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/github_com_ez-api_ez-api_internal_service.HealthStatus'
|
||||
"503":
|
||||
description: Service Unavailable
|
||||
schema:
|
||||
$ref: '#/definitions/github_com_ez-api_ez-api_internal_service.HealthStatus'
|
||||
summary: Test dependency connectivity
|
||||
tags:
|
||||
- system
|
||||
/auth/whoami:
|
||||
get:
|
||||
description: |-
|
||||
@@ -2845,6 +2857,19 @@ paths:
|
||||
summary: Ingest logs
|
||||
tags:
|
||||
- system
|
||||
/status:
|
||||
get:
|
||||
description: Returns public runtime status information without sensitive data
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/internal_api.StatusResponse'
|
||||
summary: Get system status
|
||||
tags:
|
||||
- Public
|
||||
/v1/logs:
|
||||
get:
|
||||
description: List request logs for the authenticated master
|
||||
|
||||
Reference in New Issue
Block a user