175 lines
4.3 KiB
YAML
175 lines
4.3 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Muse API
|
||
description: |
|
||
Muse AI 驱动长篇创作平台统一 API 契约。
|
||
所有接口通过 X-API-Version Header 进行版本控制。
|
||
version: 1.0.0
|
||
contact:
|
||
name: Muse Team
|
||
|
||
servers:
|
||
- url: http://localhost:48080
|
||
description: 本地开发环境
|
||
|
||
security:
|
||
- bearerAuth: []
|
||
|
||
components:
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: |
|
||
用户端使用 app-api token，管理端使用 admin-api token。
|
||
两个端点的认证域独立，token 不互通。
|
||
|
||
parameters:
|
||
XApiVersion:
|
||
name: X-API-Version
|
||
in: header
|
||
required: false
|
||
schema:
|
||
type: string
|
||
default: "2026-05-01"
|
||
description: API 版本号，格式 YYYY-MM-DD
|
||
|
||
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, message]
|
||
properties:
|
||
code:
|
||
type: integer
|
||
description: 业务状态码，0 表示成功
|
||
example: 0
|
||
message:
|
||
type: string
|
||
description: 提示信息
|
||
example: "操作成功"
|
||
data:
|
||
description: 响应数据，类型视具体接口而定
|
||
|
||
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
|
||
description: 当前页数据列表
|
||
|
||
ErrorResponse:
|
||
type: object
|
||
required: [code, message]
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: |
|
||
错误码格式: {system}-{module}-{category}-{sequence}
|
||
示例: MUSE-CONTENT-001-0001
|
||
example: "MUSE-CONTENT-001-0001"
|
||
message:
|
||
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 |