195 lines
5.0 KiB
YAML
195 lines
5.0 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Muse API
|
||
description: |
|
||
Muse AI 驱动长篇创作平台统一 API 契约。
|
||
所有接口通过 X-API-Version Header 进行版本控制。
|
||
version: 1.0.0
|
||
license:
|
||
name: Proprietary
|
||
contact:
|
||
name: Muse Team
|
||
|
||
servers:
|
||
- url: /
|
||
description: 同源 API 网关
|
||
|
||
paths: {}
|
||
|
||
components:
|
||
securitySchemes:
|
||
adminBearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: |
|
||
管理后台认证 scheme，仅用于 /admin-api/** 接口。
|
||
admin-api token 与 app-api token 不互通，接口必须按入口显式选择认证域。
|
||
appBearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: |
|
||
用户端认证 scheme，仅用于 /app-api/** 接口。
|
||
app-api token 与 admin-api token 不互通，接口必须按入口显式选择认证域。
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: |
|
||
兼容旧生成器和旧引用的 bearer 认证别名。
|
||
新增或维护接口应优先使用 adminBearerAuth 或 appBearerAuth，避免把两类 token 误判为同一认证域。
|
||
|
||
parameters:
|
||
XApiVersion:
|
||
name: X-API-Version
|
||
in: header
|
||
required: true
|
||
schema:
|
||
type: string
|
||
enum: ["1"]
|
||
example: "1"
|
||
description: |
|
||
API 版本号，当前版本为 1。
|
||
未传时网关可兼容最新稳定版本，但前端 SDK 和 API 客户端必须显式传递该 header。
|
||
|
||
pageNo:
|
||
name: pageNo
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
default: 1
|
||
description: 页码，从 1 开始
|
||
|
||
pageSize:
|
||
name: pageSize
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 100
|
||
default: 20
|
||
description: 每页条数，上限 100
|
||
|
||
schemas:
|
||
CommonResult:
|
||
type: object
|
||
required: [code, msg]
|
||
properties:
|
||
code:
|
||
type: integer
|
||
description: 业务状态码，0 表示成功
|
||
example: 0
|
||
data:
|
||
description: 响应数据，类型视具体接口而定
|
||
msg:
|
||
type: string
|
||
description: 提示信息
|
||
example: "success"
|
||
|
||
PaginatedResult:
|
||
type: object
|
||
required: [total, pageNo, pageSize, list]
|
||
properties:
|
||
total:
|
||
type: integer
|
||
description: 总记录数
|
||
example: 150
|
||
pageNo:
|
||
type: integer
|
||
description: 当前页码
|
||
example: 1
|
||
pageSize:
|
||
type: integer
|
||
description: 每页条数
|
||
example: 20
|
||
list:
|
||
type: array
|
||
items: {}
|
||
description: 当前页数据列表
|
||
|
||
ErrorResponse:
|
||
type: object
|
||
required: [code, msg]
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: |
|
||
错误码格式: {system}-{module}-{category}-{sequence}
|
||
示例: MUSE-CONTENT-001-0001
|
||
example: "MUSE-CONTENT-001-0001"
|
||
msg:
|
||
type: string
|
||
description: 人类可读的错误描述
|
||
detail:
|
||
type: string
|
||
description: 详细错误信息（仅开发环境返回）
|
||
|
||
# 通用时间戳字段
|
||
TimestampMixin:
|
||
type: object
|
||
properties:
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: 创建时间
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
description: 最后更新时间
|
||
|
||
responses:
|
||
BadRequest:
|
||
description: 请求参数有误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
Unauthorized:
|
||
description: 未认证或 token 过期
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
Forbidden:
|
||
description: 无权限
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
NotFound:
|
||
description: 资源不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
Conflict:
|
||
description: 资源冲突
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
InternalError:
|
||
description: 服务器内部错误
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
|
||
tags:
|
||
- name: Content
|
||
description: 作品、章节、Block、导出
|
||
- name: AI
|
||
description: AI 生成、候选管理、智能体、质量门控
|
||
- name: Knowledge
|
||
description: 知识实体、关系、草稿、确认
|
||
- name: Market
|
||
description: 资产发布、安装绑定、审核
|
||
- name: Account
|
||
description: 权益、配额、用量、安全事件
|
||
- name: Meta
|
||
description: MetaSchema 字段定义、版本、scope
|