refactor(api): standardize DTOs and update swagger

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

internal/dto/api_key.go

@@ -2,18 +2,43 @@ package dto
 
 import "time"
 
-// APIKeyDTO defines inbound payload for API key creation/update.
-type APIKeyDTO struct {
-	GroupID     uint      `json:"group_id"`
-	APIKey      string    `json:"api_key"`
-	AccessToken string    `json:"access_token,omitempty"`
-	RefreshToken string   `json:"refresh_token,omitempty"`
-	ExpiresAt   time.Time `json:"expires_at,omitempty"`
-	AccountID   string    `json:"account_id,omitempty"`
-	ProjectID   string    `json:"project_id,omitempty"`
-	Weight      int       `json:"weight,omitempty"`
-	Status      string    `json:"status"`
-	AutoBan     *bool     `json:"auto_ban,omitempty"`
-	BanReason   string    `json:"ban_reason,omitempty"`
-	BanUntil    time.Time `json:"ban_until,omitempty"`
+// APIKeyResponse represents an API key in API responses.
+// @Description API key response
+type APIKeyResponse struct {
+	ID              uint       `json:"id" example:"1"`
+	CreatedAt       time.Time  `json:"created_at"`
+	UpdatedAt       time.Time  `json:"updated_at"`
+	GroupID         uint       `json:"group_id" example:"1"`
+	APIKey          string     `json:"api_key" example:"sk-xxx..."`
+	AccessToken     string     `json:"access_token,omitempty"`
+	ExpiresAt       *time.Time `json:"expires_at,omitempty"`
+	AccountID       string     `json:"account_id,omitempty"`
+	ProjectID       string     `json:"project_id,omitempty"`
+	Weight          int        `json:"weight" example:"1"`
+	Status          string     `json:"status" example:"active"`
+	AutoBan         bool       `json:"auto_ban" example:"true"`
+	BanReason       string     `json:"ban_reason,omitempty"`
+	BanUntil        *time.Time `json:"ban_until,omitempty"`
+	TotalRequests   int64      `json:"total_requests" example:"1000"`
+	SuccessRequests int64      `json:"success_requests" example:"950"`
+	FailureRequests int64      `json:"failure_requests" example:"50"`
+	SuccessRate     float64    `json:"success_rate" example:"0.95"`
+	FailureRate     float64    `json:"failure_rate" example:"0.05"`
+}
+
+// APIKeyDTO defines inbound payload for API key creation/update.
+// @Description API key create/update request
+type APIKeyDTO struct {
+	GroupID      uint       `json:"group_id" example:"1"`
+	APIKey       string     `json:"api_key" example:"sk-xxx..."`
+	AccessToken  string     `json:"access_token,omitempty"`
+	RefreshToken string     `json:"refresh_token,omitempty"`
+	ExpiresAt    *time.Time `json:"expires_at,omitempty"`
+	AccountID    string     `json:"account_id,omitempty"`
+	ProjectID    string     `json:"project_id,omitempty"`
+	Weight       int        `json:"weight,omitempty" example:"1"`
+	Status       string     `json:"status" example:"active"`
+	AutoBan      *bool      `json:"auto_ban,omitempty" example:"true"`
+	BanReason    string     `json:"ban_reason,omitempty"`
+	BanUntil     *time.Time `json:"ban_until,omitempty"`
 }

internal/dto/binding.go

@@ -1,13 +1,31 @@
 package dto
 
+import "time"
+
+// BindingResponse represents a binding in API responses.
+// @Description Binding response
+type BindingResponse struct {
+	ID            uint      `json:"id" example:"1"`
+	CreatedAt     time.Time `json:"created_at"`
+	UpdatedAt     time.Time `json:"updated_at"`
+	Namespace     string    `json:"namespace" example:"default"`
+	PublicModel   string    `json:"public_model" example:"gpt-4"`
+	GroupID       uint      `json:"group_id" example:"1"`
+	Weight        int       `json:"weight" example:"1"`
+	SelectorType  string    `json:"selector_type" example:"exact"`
+	SelectorValue string    `json:"selector_value" example:"gpt-4-turbo"`
+	Status        string    `json:"status" example:"active"`
+}
+
 // BindingDTO defines inbound payload for binding creation/update.
 // It maps "(namespace, public_model)" to a ProviderGroup and an upstream selector.
+// @Description Binding create/update request
 type BindingDTO struct {
-	Namespace     string `json:"namespace"`
-	PublicModel   string `json:"public_model"`
-	GroupID       uint   `json:"group_id"`
-	Weight        int    `json:"weight"`
-	SelectorType  string `json:"selector_type"`
-	SelectorValue string `json:"selector_value"`
-	Status        string `json:"status"`
+	Namespace     string `json:"namespace" example:"default"`
+	PublicModel   string `json:"public_model" example:"gpt-4"`
+	GroupID       uint   `json:"group_id" example:"1"`
+	Weight        int    `json:"weight" example:"1"`
+	SelectorType  string `json:"selector_type" example:"exact"`
+	SelectorValue string `json:"selector_value" example:"gpt-4-turbo"`
+	Status        string `json:"status" example:"active"`
 }

internal/dto/common.go

@@ -0,0 +1,7 @@
+package dto
+
+// DeleteResponse represents a successful delete operation response.
+// @Description Delete operation response
+type DeleteResponse struct {
+	Status string `json:"status" example:"deleted"`
+}

internal/dto/log_record.go

@@ -0,0 +1,24 @@
+package dto
+
+// LogRecordRequest defines the request body for log ingestion.
+// @Description Log record ingest request
+type LogRecordRequest struct {
+	Group        string `json:"group" example:"default"`
+	MasterID     uint   `json:"master_id" example:"1"`
+	KeyID        uint   `json:"key_id" example:"1"`
+	ModelName    string `json:"model" example:"gpt-4"`
+	ProviderID   uint   `json:"provider_id" example:"1"`
+	ProviderType string `json:"provider_type" example:"openai"`
+	ProviderName string `json:"provider_name" example:"openai-prod"`
+	StatusCode   int    `json:"status_code" example:"200"`
+	LatencyMs    int64  `json:"latency_ms" example:"150"`
+	TokensIn     int64  `json:"tokens_in" example:"100"`
+	TokensOut    int64  `json:"tokens_out" example:"50"`
+	ErrorMessage string `json:"error_message,omitempty"`
+	ClientIP     string `json:"client_ip" example:"192.168.1.1"`
+	RequestSize  int64  `json:"request_size" example:"1024"`
+	ResponseSize int64  `json:"response_size" example:"2048"`
+	AuditReason  string `json:"audit_reason,omitempty"`
+	RequestBody  string `json:"request_body,omitempty"`
+	ResponseBody string `json:"response_body,omitempty"`
+}

internal/dto/log_webhook.go

@@ -0,0 +1,25 @@
+package dto
+
+// LogWebhookConfigResponse represents the log webhook configuration in API responses.
+// @Description Log webhook configuration response
+type LogWebhookConfigResponse struct {
+	Enabled             bool   `json:"enabled" example:"true"`
+	URL                 string `json:"url" example:"https://webhook.example.com/alerts"`
+	Secret              string `json:"secret" example:"webhook-secret-key"`
+	Threshold           int    `json:"threshold" example:"10"`
+	WindowSeconds       int    `json:"window_seconds" example:"60"`
+	CooldownSeconds     int    `json:"cooldown_seconds" example:"300"`
+	StatusCodeThreshold int    `json:"status_code_threshold" example:"500"`
+}
+
+// UpdateLogWebhookConfigRequest defines the request body for updating log webhook config.
+// @Description Update log webhook configuration request
+type UpdateLogWebhookConfigRequest struct {
+	Enabled             bool   `json:"enabled" example:"true"`
+	URL                 string `json:"url" example:"https://webhook.example.com/alerts"`
+	Secret              string `json:"secret" example:"webhook-secret-key"`
+	Threshold           int    `json:"threshold" example:"10"`
+	WindowSeconds       int    `json:"window_seconds" example:"60"`
+	CooldownSeconds     int    `json:"cooldown_seconds" example:"300"`
+	StatusCodeThreshold int    `json:"status_code_threshold" example:"500"`
+}

internal/dto/model.go

@@ -1,14 +1,34 @@
 package dto
 
-// ModelDTO is used for create/update of model capabilities.
-type ModelDTO struct {
-	Name               string  `json:"name"`
-	Kind               string  `json:"kind"`
-	ContextWindow      int     `json:"context_window"`
-	CostPerToken       float64 `json:"cost_per_token"`
-	SupportsVision     bool    `json:"supports_vision"`
-	SupportsFunctions  bool    `json:"supports_functions"`
-	SupportsToolChoice bool    `json:"supports_tool_choice"`
-	SupportsFIM        bool    `json:"supports_fim"`
-	MaxOutputTokens    int     `json:"max_output_tokens"`
+import "time"
+
+// ModelResponse represents a model in API responses.
+// @Description Model response
+type ModelResponse struct {
+	ID                 uint      `json:"id" example:"1"`
+	CreatedAt          time.Time `json:"created_at"`
+	UpdatedAt          time.Time `json:"updated_at"`
+	Name               string    `json:"name" example:"gpt-4"`
+	Kind               string    `json:"kind" example:"chat"`
+	ContextWindow      int       `json:"context_window" example:"128000"`
+	CostPerToken       float64   `json:"cost_per_token" example:"0.00003"`
+	SupportsVision     bool      `json:"supports_vision" example:"true"`
+	SupportsFunctions  bool      `json:"supports_functions" example:"true"`
+	SupportsToolChoice bool      `json:"supports_tool_choice" example:"true"`
+	SupportsFIM        bool      `json:"supports_fim" example:"false"`
+	MaxOutputTokens    int       `json:"max_output_tokens" example:"4096"`
+}
+
+// ModelDTO is used for create/update of model capabilities.
+// @Description Model create/update request
+type ModelDTO struct {
+	Name               string  `json:"name" example:"gpt-4"`
+	Kind               string  `json:"kind" example:"chat"`
+	ContextWindow      int     `json:"context_window" example:"128000"`
+	CostPerToken       float64 `json:"cost_per_token" example:"0.00003"`
+	SupportsVision     bool    `json:"supports_vision" example:"true"`
+	SupportsFunctions  bool    `json:"supports_functions" example:"true"`
+	SupportsToolChoice bool    `json:"supports_tool_choice" example:"true"`
+	SupportsFIM        bool    `json:"supports_fim" example:"false"`
+	MaxOutputTokens    int     `json:"max_output_tokens" example:"4096"`
 }

internal/dto/model_registry.go

@@ -0,0 +1,32 @@
+package dto
+
+// ModelRegistryStatusResponse represents the model registry status in API responses.
+// @Description Model registry status response
+type ModelRegistryStatusResponse struct {
+	Enabled       bool              `json:"enabled" example:"true"`
+	ModelsDevRef  string            `json:"models_dev_ref" example:"main"`
+	ModelsDevURL  string            `json:"models_dev_url" example:"https://models.dev/v1/models.json"`
+	LastRefreshAt int64             `json:"last_refresh_at,omitempty" example:"1704067200"`
+	LastError     string            `json:"last_error,omitempty"`
+	RedisMeta     map[string]string `json:"redis_meta,omitempty"`
+	CacheCurrent  *ModelCacheFile   `json:"cache_current,omitempty"`
+	CachePrev     *ModelCacheFile   `json:"cache_prev,omitempty"`
+}
+
+// ModelCacheFile represents a cached model registry file.
+// @Description Cached model registry file
+type ModelCacheFile struct {
+	Version   string `json:"version,omitempty"`
+	Timestamp int64  `json:"timestamp,omitempty"`
+}
+
+// ModelRegistryCheckResponse represents the result of checking model registry upstream.
+// @Description Model registry check result
+type ModelRegistryCheckResponse struct {
+	Enabled            bool   `json:"enabled" example:"true"`
+	UpstreamRef        string `json:"upstream_ref" example:"main"`
+	CurrentVersion     string `json:"current_version,omitempty" example:"abc123"`
+	LatestVersion      string `json:"latest_version,omitempty" example:"def456"`
+	NeedsRefresh       bool   `json:"needs_refresh" example:"true"`
+	CurrentUpstreamRef string `json:"current_upstream_ref,omitempty" example:"main"`
+}

internal/dto/namespace.go

@@ -0,0 +1,22 @@
+package dto
+
+import "time"
+
+// NamespaceResponse represents a namespace in API responses.
+// @Description Namespace response
+type NamespaceResponse struct {
+	ID          uint      `json:"id" example:"1"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
+	Name        string    `json:"name" example:"default"`
+	Status      string    `json:"status" example:"active"`
+	Description string    `json:"description,omitempty" example:"Default namespace"`
+}
+
+// NamespaceDTO defines inbound payload for namespace creation/update.
+// @Description Namespace create/update request
+type NamespaceDTO struct {
+	Name        string `json:"name" example:"default"`
+	Status      string `json:"status" example:"active"`
+	Description string `json:"description,omitempty" example:"Default namespace"`
+}

internal/dto/provider_group.go

@@ -1,14 +1,39 @@
 package dto
 
+import "time"
+
+// ProviderGroupResponse represents a provider group in API responses.
+// @Description Provider group response
+type ProviderGroupResponse struct {
+	ID              uint      `json:"id" example:"1"`
+	CreatedAt       time.Time `json:"created_at"`
+	UpdatedAt       time.Time `json:"updated_at"`
+	Name            string    `json:"name" example:"openai-prod"`
+	Type            string    `json:"type" example:"openai"`
+	BaseURL         string    `json:"base_url" example:"https://api.openai.com"`
+	GoogleProject   string    `json:"google_project,omitempty"`
+	GoogleLocation  string    `json:"google_location,omitempty"`
+	StaticHeaders   string    `json:"static_headers,omitempty"`
+	HeadersProfile  string    `json:"headers_profile,omitempty"`
+	Models          string    `json:"models" example:"gpt-4,gpt-3.5-turbo"`
+	Status          string    `json:"status" example:"active"`
+	TotalRequests   int64     `json:"total_requests" example:"1000"`
+	SuccessRequests int64     `json:"success_requests" example:"950"`
+	FailureRequests int64     `json:"failure_requests" example:"50"`
+	SuccessRate     float64   `json:"success_rate" example:"0.95"`
+	FailureRate     float64   `json:"failure_rate" example:"0.05"`
+}
+
 // ProviderGroupDTO defines inbound payload for provider group creation/update.
+// @Description Provider group create/update request
 type ProviderGroupDTO struct {
-	Name           string   `json:"name"`
-	Type           string   `json:"type"`
-	BaseURL        string   `json:"base_url"`
+	Name           string   `json:"name" example:"openai-prod"`
+	Type           string   `json:"type" example:"openai"`
+	BaseURL        string   `json:"base_url" example:"https://api.openai.com"`
 	GoogleProject  string   `json:"google_project,omitempty"`
 	GoogleLocation string   `json:"google_location,omitempty"`
 	StaticHeaders  string   `json:"static_headers,omitempty"`
 	HeadersProfile string   `json:"headers_profile,omitempty"`
-	Models         []string `json:"models"`
-	Status         string   `json:"status"`
+	Models         []string `json:"models" example:"gpt-4,gpt-3.5-turbo"`
+	Status         string   `json:"status" example:"active"`
 }