docs(api): update swagger documentation for admin endpoints

Reflect recent API changes in Swagger documentation:
- Add endpoints for feature flag management (/admin/features)
- Add endpoint for issuing child keys to masters (/admin/masters/{id}/keys)
- Add endpoint for updating providers (/admin/providers/{id})
- Update provider model definitions with new fields (auto_ban, google_* attributes, status)
This commit is contained in:
zenfun
2025-12-15 16:12:56 +08:00
parent aa69ce3659
commit ca03ac1b79
3 changed files with 685 additions and 0 deletions

View File

@@ -26,8 +26,18 @@ definitions:
properties:
api_key:
type: string
auto_ban:
type: boolean
ban_reason:
type: string
ban_until:
type: string
base_url:
type: string
google_location:
type: string
google_project:
type: string
group:
type: string
models:
@@ -37,6 +47,11 @@ definitions:
type: array
name:
type: string
skip_routing:
description: Optional control params
type: boolean
status:
type: string
type:
type: string
type: object
@@ -112,12 +127,25 @@ definitions:
properties:
api_key:
type: string
auto_ban:
description: whether DP-triggered disable is allowed
type: boolean
ban_reason:
description: reason for current disable
type: string
ban_until:
description: optional TTL for disable
type: string
base_url:
type: string
createdAt:
type: string
deletedAt:
$ref: '#/definitions/gorm.DeletedAt'
google_location:
type: string
google_project:
type: string
group:
description: routing group/tier
type: string
@@ -128,6 +156,9 @@ definitions:
type: string
name:
type: string
status:
description: active, auto_disabled, manual_disabled
type: string
type:
description: openai, anthropic, etc.
type: string
@@ -177,6 +208,57 @@ info:
title: EZ-API Control Plane
version: 0.0.1
paths:
/admin/features:
get:
description: Returns all feature flags stored in Redis (meta:features)
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: List feature flags
tags:
- admin
put:
consumes:
- application/json
description: Updates selected feature flags (meta:features). Values are stored
as strings.
parameters:
- description: Feature map
in: body
name: request
required: true
schema:
type: object
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/gin.H'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Update feature flags
tags:
- admin
/admin/masters:
post:
consumes:
@@ -209,6 +291,52 @@ paths:
summary: Create a new master tenant
tags:
- admin
/admin/masters/{id}/keys:
post:
consumes:
- application/json
description: Issue a new access token (child key) for a specified master. The
key still belongs to the master; issuer is recorded as admin for audit.
parameters:
- description: Master ID
in: path
name: id
required: true
type: integer
- description: Key Request
in: body
name: request
required: true
schema:
$ref: '#/definitions/internal_api.IssueChildKeyRequest'
produces:
- application/json
responses:
"201":
description: Created
schema:
$ref: '#/definitions/gin.H'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"403":
description: Forbidden
schema:
$ref: '#/definitions/gin.H'
"404":
description: Not Found
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Issue a child key on behalf of a master
tags:
- admin
/admin/models:
get:
description: Get a list of all registered models
@@ -334,6 +462,47 @@ paths:
summary: Create a new provider
tags:
- admin
/admin/providers/{id}:
put:
consumes:
- application/json
description: Update provider attributes including status/auto-ban flags
parameters:
- description: Provider ID
in: path
name: id
required: true
type: integer
- description: Provider Info
in: body
name: provider
required: true
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderDTO'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Provider'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"404":
description: Not Found
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Update a provider
tags:
- admin
/admin/sync/snapshot:
post:
description: Force full synchronization of DB state to Redis