docs(api): 补全 OpenAPI 上传与系统设置文档

为文件上传、静态资源和文件存储设置接口补齐注释，并同步更新生成的 Swagger 文档。
2026-05-15 09:59:25 +08:00
parent 62d426bdfb
commit 34c3251c6d
6 changed files with 1300 additions and 0 deletions
@@ -138,6 +138,34 @@ definitions:
        example: 400
        type: integer
    type: object
+  httpapi.FileStorageChannelListResponse:
+    properties:
+      items:
+        items:
+          $ref: '#/definitions/store.FileStorageChannel'
+        type: array
+    type: object
+  httpapi.FileUploadResponse:
+    properties:
+      assetStorage:
+        additionalProperties: true
+        type: object
+      contentType:
+        example: image/png
+        type: string
+      filename:
+        example: image.png
+        type: string
+      id:
+        example: file_abc123
+        type: string
+      size:
+        example: 1024
+        type: integer
+      url:
+        example: /static/uploaded/upload-abc123.png
+        type: string
+    type: object
  httpapi.HealthResponse:
    properties:
      env:
@@ -1045,6 +1073,83 @@ definitions:
      secret:
        type: string
    type: object
+  store.FileStorageChannel:
+    properties:
+      channelKey:
+        type: string
+      config:
+        additionalProperties: {}
+        type: object
+      createdAt:
+        type: string
+      credentialsPreview:
+        additionalProperties: {}
+        type: object
+      id:
+        type: string
+      lastError:
+        type: string
+      lastFailedAt:
+        type: string
+      lastSucceededAt:
+        type: string
+      name:
+        type: string
+      priority:
+        type: integer
+      provider:
+        type: string
+      retryPolicy:
+        additionalProperties: {}
+        type: object
+      scenes:
+        items:
+          type: string
+        type: array
+      status:
+        type: string
+      updatedAt:
+        type: string
+      uploadUrl:
+        type: string
+    type: object
+  store.FileStorageChannelInput:
+    properties:
+      apiKey:
+        type: string
+      channelKey:
+        type: string
+      config:
+        additionalProperties: {}
+        type: object
+      name:
+        type: string
+      priority:
+        type: integer
+      provider:
+        type: string
+      retryPolicy:
+        additionalProperties: {}
+        type: object
+      scenes:
+        items:
+          type: string
+        type: array
+      status:
+        type: string
+      uploadUrl:
+        type: string
+    type: object
+  store.FileStorageSettings:
+    properties:
+      resultUploadPolicy:
+        type: string
+    type: object
+  store.FileStorageSettingsInput:
+    properties:
+      resultUploadPolicy:
+        type: string
+    type: object
  store.GatewayTask:
    properties:
      apiKeyId:
@@ -3644,6 +3749,229 @@ paths:
      summary: 更新 Runner 策略
      tags:
      - runtime
+  /api/admin/system/file-storage/channels:
+    get:
+      description: 返回所有未删除的文件存储通道，用于管理上传与生成资源回传策略。
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/httpapi.FileStorageChannelListResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 列出文件存储通道
+      tags:
+      - system
+    post:
+      consumes:
+      - application/json
+      description: 创建文件存储通道，当前主要用于配置 server-main OpenAPI 上传通道。
+      parameters:
+      - description: 文件存储通道
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/store.FileStorageChannelInput'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/store.FileStorageChannel'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 创建文件存储通道
+      tags:
+      - system
+  /api/admin/system/file-storage/channels/{channelID}:
+    delete:
+      description: 软删除指定文件存储通道。
+      parameters:
+      - description: 文件存储通道 ID
+        in: path
+        name: channelID
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "204":
+          description: No Content
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 删除文件存储通道
+      tags:
+      - system
+    patch:
+      consumes:
+      - application/json
+      description: 更新指定文件存储通道的名称、凭证、场景、优先级、状态和重试策略。
+      parameters:
+      - description: 文件存储通道 ID
+        in: path
+        name: channelID
+        required: true
+        type: string
+      - description: 文件存储通道
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/store.FileStorageChannelInput'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/store.FileStorageChannel'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 更新文件存储通道
+      tags:
+      - system
+  /api/admin/system/file-storage/settings:
+    get:
+      description: 返回文件存储系统设置；数据库对象尚未创建时返回默认设置。
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/store.FileStorageSettings'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 获取文件存储设置
+      tags:
+      - system
+    patch:
+      consumes:
+      - application/json
+      description: 更新生成资源上传策略等文件存储系统设置。
+      parameters:
+      - description: 文件存储设置
+        in: body
+        name: body
+        required: true
+        schema:
+          $ref: '#/definitions/store.FileStorageSettingsInput'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/store.FileStorageSettings'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 更新文件存储设置
+      tags:
+      - system
  /api/admin/tenants:
    get:
      description: 管理端返回网关租户列表。
@@ -4529,6 +4857,50 @@ paths:
      summary: 创建或执行 AI 任务
      tags:
      - tasks
+  /api/v1/files/upload:
+    post:
+      consumes:
+      - multipart/form-data
+      description: 上传文件到配置的文件存储通道；没有启用通道时回退到本地静态上传目录。单文件最大 256MiB。
+      parameters:
+      - description: 要上传的文件
+        in: formData
+        name: file
+        required: true
+        type: file
+      - default: ai-gateway-openapi
+        description: 上传来源标识
+        in: formData
+        name: source
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/httpapi.FileUploadResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "502":
+          description: Bad Gateway
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 上传文件
+      tags:
+      - files
  /api/v1/images/edits:
    post:
      consumes:
@@ -5633,6 +6005,29 @@ paths:
      summary: 创建或执行 AI 任务
      tags:
      - tasks
+  /static/generated/{asset}:
+    get:
+      description: 从本地生成资源目录读取图片、视频等任务产物；不存在时返回 404。
+      parameters:
+      - description: 资源文件名
+        in: path
+        name: asset
+        required: true
+        type: string
+      produces:
+      - application/octet-stream
+      responses:
+        "200":
+          description: OK
+          schema:
+            type: file
+        "404":
+          description: Not Found
+          schema:
+            type: string
+      summary: 获取本地生成资源
+      tags:
+      - static
  /static/simulation/{asset}:
    get:
      description: 返回本地模拟模式使用的图片、视频封面或短视频资源。
@@ -5657,6 +6052,29 @@ paths:
      summary: 获取模拟资源
      tags:
      - simulation
+  /static/uploaded/{asset}:
+    get:
+      description: 从本地上传资源目录读取用户上传文件；不存在时返回 404。
+      parameters:
+      - description: 资源文件名
+        in: path
+        name: asset
+        required: true
+        type: string
+      produces:
+      - application/octet-stream
+      responses:
+        "200":
+          description: OK
+          schema:
+            type: file
+        "404":
+          description: Not Found
+          schema:
+            type: string
+      summary: 获取本地上传资源
+      tags:
+      - static
  /v1/chat/completions:
    post:
      consumes:
@@ -5718,6 +6136,50 @@ paths:
      summary: 创建或执行 AI 任务
      tags:
      - tasks
+  /v1/files/upload:
+    post:
+      consumes:
+      - multipart/form-data
+      description: 上传文件到配置的文件存储通道；没有启用通道时回退到本地静态上传目录。单文件最大 256MiB。
+      parameters:
+      - description: 要上传的文件
+        in: formData
+        name: file
+        required: true
+        type: file
+      - default: ai-gateway-openapi
+        description: 上传来源标识
+        in: formData
+        name: source
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/httpapi.FileUploadResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "502":
+          description: Bad Gateway
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/httpapi.ErrorEnvelope'
+      security:
+      - BearerAuth: []
+      summary: 上传文件
+      tags:
+      - files
  /v1/images/edits:
    post:
      consumes: