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

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

docs/swagger.yaml

@@ -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:
-        type: integer
+        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:
+      deletedAt:
-        type: string
+        $ref: '#/definitions/gorm.DeletedAt'
-      google_project:
+      group_id:
-        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:
         type: integer
-    type: object
+      id:
-  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:
         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
+      description: Delete a provider group and its api keys/bindings
-        routing
       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
+      summary: Update provider group
-      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
       tags:
       - admin
   /admin/stats: