ruochen/ez-api
1
0
Fork 0
mirror of https://github.com/EZ-Api/ez-api.git synced 2026-01-13 17:47:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update swagger specs for provider-groups and api-keys refactor

Browse Source 
Regenerate OpenAPI documentation to reflect the architectural split
of Provider into ProviderGroup and APIKey models:

- Replace /admin/providers endpoints with /admin/provider-groups
- Add new /admin/api-keys CRUD and batch endpoints
- Update BindingDTO to use group_id instead of route_group
- Remove provider-specific DTOs (ProviderCustomCreateDTO, ProviderPresetCreateDTO, ProviderGoogleCreateDTO)
- Add APIKeyDTO and ProviderGroupDTO definitions
- Update model definitions for APIKey, Binding, and ProviderGroup
This commit is contained in:
zenfun
2025-12-24 02:20:32 +08:00
parent dea8363e41
commit d731e42ae5
3 changed files with 1078 additions and 1350 deletions
Download Patch File Download Diff File Expand all files Collapse all files

620
docs/swagger.yaml
View File

@@ -3,20 +3,39 @@ definitions:
gin.H:
additionalProperties: {}
type: object
github_com_ez-api_ez-api_internal_dto.APIKeyDTO:
properties:
api_key:
type: string
auto_ban:
type: boolean
ban_reason:
type: string
ban_until:
type: string
group_id:
type: integer
status:
type: string
weight:
type: integer
type: object
github_com_ez-api_ez-api_internal_dto.BindingDTO:
properties:
group_id:
type: integer
namespace:
type: string
public_model:
type: string
route_group:
type: string
selector_type:
type: string
selector_value:
type: string
status:
type: string
weight:
type: integer
type: object
github_com_ez-api_ez-api_internal_dto.ModelDTO:
properties:
@@ -39,15 +58,13 @@ definitions:
supports_vision:
type: boolean
type: object
github_com_ez-api_ez-api_internal_dto.ProviderCustomCreateDTO:
github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO:
properties:
api_key:
type: string
auto_ban:
type: boolean
base_url:
type: string
group:
google_location:
type: string
google_project:
type: string
models:
items:
@@ -57,10 +74,10 @@ definitions:
type: string
status:
type: string
weight:
type: integer
type:
type: string
type: object
github_com_ez-api_ez-api_internal_dto.ProviderDTO:
github_com_ez-api_ez-api_internal_model.APIKey:
properties:
api_key:
type: string
@@ -70,87 +87,18 @@ definitions:
type: string
ban_until:
type: string
base_url:
createdAt:
type: string
google_location:
type: string
google_project:
type: string
group:
type: string
models:
description: List of supported model names
items:
type: string
type: array
name:
type: string
skip_routing:
description: Optional control params
type: boolean
status:
type: string
type:
type: string
weight:
deletedAt:
$ref: '#/definitions/gorm.DeletedAt'
group_id:
type: integer
type: object
github_com_ez-api_ez-api_internal_dto.ProviderGoogleCreateDTO:
properties:
api_key:
description: Gemini API
type: string
auto_ban:
type: boolean
google_location:
type: string
google_project:
description: Vertex
type: string
group:
type: string
models:
items:
type: string
type: array
name:
description: Optional fields.
type: string
status:
type: string
type:
description: |-
Type must be a Google-family provider type, e.g.:
- gemini/google/aistudio (Gemini API)
- vertex/vertex-express (Vertex)
type: string
weight:
id:
type: integer
type: object
github_com_ez-api_ez-api_internal_dto.ProviderPresetCreateDTO:
properties:
api_key:
type: string
auto_ban:
type: boolean
google_location:
type: string
google_project:
type: string
group:
type: string
models:
items:
type: string
type: array
name:
description: Optional fields.
type: string
preset:
description: openai | anthropic | gemini
type: string
status:
type: string
updatedAt:
type: string
weight:
type: integer
type: object
@@ -160,14 +108,14 @@ definitions:
type: string
deletedAt:
$ref: '#/definitions/gorm.DeletedAt'
group_id:
type: integer
id:
type: integer
namespace:
type: string
public_model:
type: string
route_group:
type: string
selector_type:
type: string
selector_value:
@@ -176,6 +124,8 @@ definitions:
type: string
updatedAt:
type: string
weight:
type: integer
type: object
github_com_ez-api_ez-api_internal_model.LogRecord:
properties:
@@ -270,19 +220,8 @@ definitions:
updatedAt:
type: string
type: object
github_com_ez-api_ez-api_internal_model.Provider:
github_com_ez-api_ez-api_internal_model.ProviderGroup:
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:
@@ -293,27 +232,20 @@ definitions:
type: string
google_project:
type: string
group:
description: routing group/tier
type: string
id:
type: integer
models:
description: comma-separated list of supported models (e.g. "gpt-4,gpt-3.5-turbo")
description: comma-separated list of supported models
type: string
name:
type: string
status:
description: active, auto_disabled, manual_disabled
type: string
type:
description: openai, anthropic, etc.
description: openai, anthropic, gemini
type: string
updatedAt:
type: string
weight:
description: routing weight inside route_group
type: integer
type: object
github_com_ez-api_ez-api_internal_service.HealthStatus:
properties:
@@ -822,17 +754,6 @@ definitions:
$ref: '#/definitions/internal_api.statsFlushEntry'
type: array
type: object
internal_api.testProviderResponse:
properties:
body:
type: string
ok:
type: boolean
status_code:
type: integer
url:
type: string
type: object
modelcap.Meta:
properties:
checksum:
@@ -885,6 +806,208 @@ info:
title: EZ-API Control Plane
version: 0.0.1
paths:
/admin/api-keys:
get:
description: List API keys
parameters:
- description: page (1-based)
in: query
name: page
type: integer
- description: limit (default 50, max 200)
in: query
name: limit
type: integer
- description: filter by group_id
in: query
name: group_id
type: integer
produces:
- application/json
responses:
"200":
description: OK
schema:
items:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.APIKey'
type: array
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: List API keys
tags:
- admin
post:
consumes:
- application/json
description: Create an API key for a provider group
parameters:
- description: API key payload
in: body
name: key
required: true
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.APIKeyDTO'
produces:
- application/json
responses:
"201":
description: Created
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.APIKey'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Create an API key
tags:
- admin
/admin/api-keys/{id}:
delete:
description: Delete an API key
parameters:
- description: APIKey ID
in: path
name: id
required: true
type: integer
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/gin.H'
"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: Delete API key
tags:
- admin
get:
description: Get an API key by id
parameters:
- description: APIKey ID
in: path
name: id
required: true
type: integer
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.APIKey'
"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: Get API key
tags:
- admin
put:
consumes:
- application/json
description: Update an API key
parameters:
- description: APIKey ID
in: path
name: id
required: true
type: integer
- description: API key payload
in: body
name: key
required: true
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.APIKeyDTO'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.APIKey'
"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 API key
tags:
- admin
/admin/api-keys/batch:
post:
consumes:
- application/json
description: Batch delete or status update for api keys
parameters:
- description: Batch payload
in: body
name: request
required: true
schema:
$ref: '#/definitions/internal_api.BatchActionRequest'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/internal_api.BatchResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Batch api keys
tags:
- admin
/admin/bindings:
get:
description: List all configured bindings
@@ -897,7 +1020,7 @@ paths:
in: query
name: limit
type: integer
- description: search by namespace/public_model/route_group
- description: search by namespace/public_model
in: query
name: search
type: string
@@ -922,7 +1045,7 @@ paths:
post:
consumes:
- application/json
description: Create a new (namespace, public_model) binding to a route group
description: Create a new (namespace, public_model) binding to a provider group
and selector
parameters:
- description: Binding Info
@@ -2247,9 +2370,9 @@ paths:
summary: List operation logs
tags:
- admin
/admin/providers:
/admin/provider-groups:
get:
description: List all configured upstream providers
description: List all provider groups
parameters:
- description: page (1-based)
in: query
@@ -2259,7 +2382,7 @@ paths:
in: query
name: limit
type: integer
- description: search by name/type/base_url/group
- description: search by name/type
in: query
name: search
type: string
@@ -2270,7 +2393,7 @@ paths:
description: OK
schema:
items:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Provider'
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup'
type: array
"500":
description: Internal Server Error
@@ -2278,27 +2401,27 @@ paths:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: List providers
summary: List provider groups
tags:
- admin
post:
consumes:
- application/json
description: Register a new upstream AI provider
description: Create a provider group definition
parameters:
- description: Provider Info
- description: Provider group payload
in: body
name: provider
name: group
required: true
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderDTO'
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO'
produces:
- application/json
responses:
"201":
description: Created
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Provider'
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup'
"400":
description: Bad Request
schema:
@@ -2309,15 +2432,14 @@ paths:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Create a new provider
summary: Create a provider group
tags:
- admin
/admin/providers/{id}:
/admin/provider-groups/{id}:
delete:
description: Deletes a provider and triggers a full snapshot sync to avoid stale
routing
description: Delete a provider group and its api keys/bindings
parameters:
- description: Provider ID
- description: ProviderGroup ID
in: path
name: id
required: true
@@ -2343,13 +2465,13 @@ paths:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Delete provider
summary: Delete provider group
tags:
- admin
get:
description: Get a provider by id
description: Get a provider group by id
parameters:
- description: Provider ID
- description: ProviderGroup ID
in: path
name: id
required: true
@@ -2360,7 +2482,7 @@ paths:
"200":
description: OK
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Provider'
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup'
"400":
description: Bad Request
schema:
@@ -2375,32 +2497,32 @@ paths:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Get provider
summary: Get provider group
tags:
- admin
put:
consumes:
- application/json
description: Update provider attributes including status/auto-ban flags
description: Update a provider group
parameters:
- description: Provider ID
- description: ProviderGroup ID
in: path
name: id
required: true
type: integer
- description: Provider Info
- description: Provider group payload
in: body
name: provider
name: group
required: true
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderDTO'
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGroupDTO'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Provider'
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.ProviderGroup'
"400":
description: Bad Request
schema:
@@ -2415,205 +2537,7 @@ paths:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Update a provider
tags:
- admin
/admin/providers/{id}/fetch-models:
post:
description: Calls upstream /models (or /v1/models) and updates provider model
list
parameters:
- description: Provider ID
in: path
name: id
required: true
type: integer
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/gin.H'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"404":
description: Not Found
schema:
$ref: '#/definitions/gin.H'
"502":
description: Bad Gateway
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Fetch models from provider
tags:
- admin
/admin/providers/{id}/test:
post:
description: Performs a lightweight upstream request to verify the provider
configuration
parameters:
- description: Provider ID
in: path
name: id
required: true
type: integer
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/internal_api.testProviderResponse'
"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: Test provider connectivity
tags:
- admin
/admin/providers/batch:
post:
consumes:
- application/json
description: Batch delete or status update for providers
parameters:
- description: Batch payload
in: body
name: request
required: true
schema:
$ref: '#/definitions/internal_api.BatchActionRequest'
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/internal_api.BatchResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Batch providers
tags:
- admin
/admin/providers/custom:
post:
consumes:
- application/json
description: Create an OpenAI-compatible provider (base_url + api_key required)
parameters:
- description: Provider custom payload
in: body
name: provider
required: true
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderCustomCreateDTO'
produces:
- application/json
responses:
"201":
description: Created
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Provider'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Create a custom provider
tags:
- admin
/admin/providers/google:
post:
consumes:
- application/json
description: Create a Google SDK provider (Gemini API key or Vertex project/location);
base_url is not used
parameters:
- description: Google provider payload
in: body
name: provider
required: true
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderGoogleCreateDTO'
produces:
- application/json
responses:
"201":
description: Created
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Provider'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Create a Google SDK provider
tags:
- admin
/admin/providers/preset:
post:
consumes:
- application/json
description: Create an official OpenAI/Anthropic provider (only api_key is typically
required)
parameters:
- description: Provider preset payload
in: body
name: provider
required: true
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_dto.ProviderPresetCreateDTO'
produces:
- application/json
responses:
"201":
description: Created
schema:
$ref: '#/definitions/github_com_ez-api_ez-api_internal_model.Provider'
"400":
description: Bad Request
schema:
$ref: '#/definitions/gin.H'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/gin.H'
security:
- AdminAuth: []
summary: Create a preset provider
summary: Update provider group
tags:
- admin
/admin/stats: