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

refactor(api): standardize DTOs and update swagger

Browse Source 
Decouple API contract from internal models by introducing dedicated DTOs for requests and responses.
- Add Response DTOs for all resources (API Keys, Bindings, Models, Namespaces, etc.)
- Update Swagger annotations to use DTOs with field examples instead of internal models
- Refactor handlers to bind and return DTO structures
- Consolidate request/response definitions in the dto package
This commit is contained in:
zenfun
2026-01-10 02:05:55 +08:00
parent f52c7acbe6
commit 2098bc4abe
20 changed files with 4156 additions and 3760 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
internal/api/admin_handler.go
View File

@@ -489,8 +489,8 @@ func (h *AdminHandler) IssueChildKeyForMaster(c *gin.Context) {
// @Param limit query int false "limit (default 50, max 200)"
// @Param search query string false "search by group/scopes/namespaces/status"
// @Success 200 {object} ResponseEnvelope{data=[]TokenView}
// @Failure 400 {object} ResponseEnvelope{data=gin.H}
// @Failure 500 {object} ResponseEnvelope{data=gin.H}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/masters/{id}/keys [get]
func (h *AdminHandler) ListKeysForMaster(c *gin.Context) {
masterID, ok := parseUintParam(c, "id")
@@ -523,10 +523,10 @@ func (h *AdminHandler) ListKeysForMaster(c *gin.Context) {
// @Security AdminAuth
// @Param id path int true "Master ID"
// @Param key_id path int true "Token ID"
// @Success 200 {object} ResponseEnvelope{data=gin.H}
// @Failure 400 {object} ResponseEnvelope{data=gin.H}
// @Failure 404 {object} ResponseEnvelope{data=gin.H}
// @Failure 500 {object} ResponseEnvelope{data=gin.H}
// @Success 200 {object} ResponseEnvelope{data=dto.DeleteResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/masters/{id}/keys/{key_id} [delete]
func (h *AdminHandler) DeleteKeyForMaster(c *gin.Context) {
masterID, ok := parseUintParam(c, "id")

8
internal/api/api_key_handler.go
View File

@@ -17,7 +17,7 @@ import (
// @Produce json
// @Security AdminAuth
// @Param key body dto.APIKeyDTO true "API key payload"
// @Success 201 {object} ResponseEnvelope{data=model.APIKey}
// @Success 201 {object} ResponseEnvelope{data=dto.APIKeyResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/api-keys [post]
@@ -100,7 +100,7 @@ func (h *Handler) CreateAPIKey(c *gin.Context) {
// @Param limit query int false "limit (default 50, max 200)"
// @Param group_id query int false "filter by group_id"
// @Param status query string false "filter by status (active, suspended, auto_disabled, manual_disabled)"
// @Success 200 {object} ResponseEnvelope{data=[]model.APIKey}
// @Success 200 {object} ResponseEnvelope{data=[]dto.APIKeyResponse}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/api-keys [get]
func (h *Handler) ListAPIKeys(c *gin.Context) {
@@ -128,7 +128,7 @@ func (h *Handler) ListAPIKeys(c *gin.Context) {
// @Produce json
// @Security AdminAuth
// @Param id path int true "APIKey ID"
// @Success 200 {object} ResponseEnvelope{data=model.APIKey}
// @Success 200 {object} ResponseEnvelope{data=dto.APIKeyResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
@@ -155,7 +155,7 @@ func (h *Handler) GetAPIKey(c *gin.Context) {
// @Security AdminAuth
// @Param id path int true "APIKey ID"
// @Param key body dto.APIKeyDTO true "API key payload"
// @Success 200 {object} ResponseEnvelope{data=model.APIKey}
// @Success 200 {object} ResponseEnvelope{data=dto.APIKeyResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}

8
internal/api/binding_handler.go
View File

@@ -19,7 +19,7 @@ import (
// @Produce json
// @Security AdminAuth
// @Param binding body dto.BindingDTO true "Binding Info"
// @Success 201 {object} ResponseEnvelope{data=model.Binding}
// @Success 201 {object} ResponseEnvelope{data=dto.BindingResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/bindings [post]
@@ -84,7 +84,7 @@ func (h *Handler) CreateBinding(c *gin.Context) {
// @Param page query int false "page (1-based)"
// @Param limit query int false "limit (default 50, max 200)"
// @Param search query string false "search by namespace/public_model"
// @Success 200 {object} ResponseEnvelope{data=[]model.Binding}
// @Success 200 {object} ResponseEnvelope{data=[]dto.BindingResponse}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/bindings [get]
func (h *Handler) ListBindings(c *gin.Context) {
@@ -109,7 +109,7 @@ func (h *Handler) ListBindings(c *gin.Context) {
// @Security AdminAuth
// @Param id path int true "Binding ID"
// @Param binding body dto.BindingDTO true "Binding Info"
// @Success 200 {object} ResponseEnvelope{data=model.Binding}
// @Success 200 {object} ResponseEnvelope{data=dto.BindingResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
@@ -180,7 +180,7 @@ func (h *Handler) UpdateBinding(c *gin.Context) {
// @Produce json
// @Security AdminAuth
// @Param id path int true "Binding ID"
// @Success 200 {object} ResponseEnvelope{data=model.Binding}
// @Success 200 {object} ResponseEnvelope{data=dto.BindingResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}

8
internal/api/handler.go
View File

@@ -62,7 +62,7 @@ func (h *Handler) logBaseQuery() *gorm.DB {
// @Produce json
// @Security AdminAuth
// @Param model body dto.ModelDTO true "Model Info"
// @Success 201 {object} ResponseEnvelope{data=model.Model}
// @Success 201 {object} ResponseEnvelope{data=dto.ModelResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/models [post]
@@ -123,7 +123,7 @@ func (h *Handler) CreateModel(c *gin.Context) {
// @Param page query int false "page (1-based)"
// @Param limit query int false "limit (default 50, max 200)"
// @Param search query string false "search by name/kind"
// @Success 200 {object} ResponseEnvelope{data=[]model.Model}
// @Success 200 {object} ResponseEnvelope{data=[]dto.ModelResponse}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/models [get]
func (h *Handler) ListModels(c *gin.Context) {
@@ -148,7 +148,7 @@ func (h *Handler) ListModels(c *gin.Context) {
// @Security AdminAuth
// @Param id path int true "Model ID"
// @Param model body dto.ModelDTO true "Model Info"
// @Success 200 {object} ResponseEnvelope{data=model.Model}
// @Success 200 {object} ResponseEnvelope{data=dto.ModelResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
@@ -277,7 +277,7 @@ func (h *Handler) SyncSnapshot(c *gin.Context) {
// @Tags system
// @Accept json
// @Produce json
// @Param log body model.LogRecord true "Log Record"
// @Param log body dto.LogRecordRequest true "Log Record"
// @Success 202 {object} ResponseEnvelope{data=MapData}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Router /logs [post]

13
internal/api/log_webhook_handler.go
View File

@@ -3,17 +3,24 @@ package api
import (
"net/http"
"github.com/ez-api/ez-api/internal/dto"
"github.com/ez-api/ez-api/internal/service"
"github.com/gin-gonic/gin"
)
// Ensure dto types are referenced for swagger generation
var (
_ dto.LogWebhookConfigResponse
_ dto.UpdateLogWebhookConfigRequest
)
// GetLogWebhookConfig godoc
// @Summary Get log webhook config
// @Description Returns current webhook notification config
// @Tags admin
// @Produce json
// @Security AdminAuth
// @Success 200 {object} ResponseEnvelope{data=service.LogWebhookConfig}
// @Success 200 {object} ResponseEnvelope{data=dto.LogWebhookConfigResponse}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/logs/webhook [get]
func (h *Handler) GetLogWebhookConfig(c *gin.Context) {
@@ -36,8 +43,8 @@ func (h *Handler) GetLogWebhookConfig(c *gin.Context) {
// @Accept json
// @Produce json
// @Security AdminAuth
// @Param request body service.LogWebhookConfig true "Webhook config"
// @Success 200 {object} ResponseEnvelope{data=service.LogWebhookConfig}
// @Param request body dto.UpdateLogWebhookConfigRequest true "Webhook config"
// @Success 200 {object} ResponseEnvelope{data=dto.LogWebhookConfigResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/logs/webhook [put]

4
internal/api/model_registry_handler.go
View File

@@ -22,7 +22,7 @@ func NewModelRegistryHandler(reg *service.ModelRegistryService) *ModelRegistryHa
// @Tags admin
// @Produce json
// @Security AdminAuth
// @Success 200 {object} ResponseEnvelope{data=service.ModelRegistryStatus}
// @Success 200 {object} ResponseEnvelope{data=dto.ModelRegistryStatusResponse}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/model-registry/status [get]
func (h *ModelRegistryHandler) GetStatus(c *gin.Context) {
@@ -50,7 +50,7 @@ type refreshModelRegistryRequest struct {
// @Produce json
// @Security AdminAuth
// @Param body body refreshModelRegistryRequest false "optional override ref"
// @Success 200 {object} ResponseEnvelope{data=service.ModelRegistryCheckResult}
// @Success 200 {object} ResponseEnvelope{data=dto.ModelRegistryCheckResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/model-registry/check [post]

21
internal/api/namespace_handler.go
View File

@@ -4,16 +4,11 @@ import (
"net/http"
"strings"
"github.com/ez-api/ez-api/internal/dto"
"github.com/ez-api/ez-api/internal/model"
"github.com/gin-gonic/gin"
)
type NamespaceRequest struct {
Name string `json:"name"`
Status string `json:"status"`
Description string `json:"description"`
}
// CreateNamespace godoc
// @Summary Create namespace
// @Description Create a namespace for bindings
@@ -21,13 +16,13 @@ type NamespaceRequest struct {
// @Accept json
// @Produce json
// @Security AdminAuth
// @Param namespace body NamespaceRequest true "Namespace payload"
// @Success 201 {object} ResponseEnvelope{data=model.Namespace}
// @Param namespace body dto.NamespaceDTO true "Namespace payload"
// @Success 201 {object} ResponseEnvelope{data=dto.NamespaceResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/namespaces [post]
func (h *Handler) CreateNamespace(c *gin.Context) {
var req NamespaceRequest
var req dto.NamespaceDTO
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
@@ -64,7 +59,7 @@ func (h *Handler) CreateNamespace(c *gin.Context) {
// @Param page query int false "page (1-based)"
// @Param limit query int false "limit (default 50, max 200)"
// @Param search query string false "search by name/description"
// @Success 200 {object} ResponseEnvelope{data=[]model.Namespace}
// @Success 200 {object} ResponseEnvelope{data=[]dto.NamespaceResponse}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/namespaces [get]
func (h *Handler) ListNamespaces(c *gin.Context) {
@@ -87,7 +82,7 @@ func (h *Handler) ListNamespaces(c *gin.Context) {
// @Produce json
// @Security AdminAuth
// @Param id path int true "Namespace ID"
// @Success 200 {object} ResponseEnvelope{data=model.Namespace}
// @Success 200 {object} ResponseEnvelope{data=dto.NamespaceResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
@@ -118,9 +113,9 @@ type UpdateNamespaceRequest struct {
// @Accept json
// @Produce json
// @Security AdminAuth
// @Param id path int true "Namespace ID"
// @Param id path int true "Namespace ID"
// @Param namespace body UpdateNamespaceRequest true "Update payload"
// @Success 200 {object} ResponseEnvelope{data=model.Namespace}
// @Success 200 {object} ResponseEnvelope{data=dto.NamespaceResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}

8
internal/api/provider_group_handler.go
View File

@@ -19,7 +19,7 @@ import (
// @Produce json
// @Security AdminAuth
// @Param group body dto.ProviderGroupDTO true "Provider group payload"
// @Success 201 {object} ResponseEnvelope{data=model.ProviderGroup}
// @Success 201 {object} ResponseEnvelope{data=dto.ProviderGroupResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/provider-groups [post]
@@ -78,7 +78,7 @@ func (h *Handler) CreateProviderGroup(c *gin.Context) {
// @Param page query int false "page (1-based)"
// @Param limit query int false "limit (default 50, max 200)"
// @Param search query string false "search by name/type"
// @Success 200 {object} ResponseEnvelope{data=[]model.ProviderGroup}
// @Success 200 {object} ResponseEnvelope{data=[]dto.ProviderGroupResponse}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
// @Router /admin/provider-groups [get]
func (h *Handler) ListProviderGroups(c *gin.Context) {
@@ -101,7 +101,7 @@ func (h *Handler) ListProviderGroups(c *gin.Context) {
// @Produce json
// @Security AdminAuth
// @Param id path int true "ProviderGroup ID"
// @Success 200 {object} ResponseEnvelope{data=model.ProviderGroup}
// @Success 200 {object} ResponseEnvelope{data=dto.ProviderGroupResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}
@@ -128,7 +128,7 @@ func (h *Handler) GetProviderGroup(c *gin.Context) {
// @Security AdminAuth
// @Param id path int true "ProviderGroup ID"
// @Param group body dto.ProviderGroupDTO true "Provider group payload"
// @Success 200 {object} ResponseEnvelope{data=model.ProviderGroup}
// @Success 200 {object} ResponseEnvelope{data=dto.ProviderGroupResponse}
// @Failure 400 {object} ResponseEnvelope{data=MapData}
// @Failure 404 {object} ResponseEnvelope{data=MapData}
// @Failure 500 {object} ResponseEnvelope{data=MapData}