Files
quyun-v2/api-spec.yaml
2025-12-27 19:49:11 +08:00

1126 lines
25 KiB
YAML

openapi: 3.0.0
info:
title: Quyun Platform API
description: API specification for Quyun (曲韵) Platform - A multi-tenant opera content delivery platform.
version: 1.0.2
servers:
- url: /v1
description: Production Server
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
# --- Common Models ---
Error:
type: object
properties:
code:
type: integer
message:
type: string
Pagination:
type: object
properties:
page:
type: integer
pageSize:
type: integer
total:
type: integer
# --- User Models ---
User:
type: object
properties:
id:
type: string
phone:
type: string
nickname:
type: string
avatar:
type: string
gender:
type: string
enum: [male, female, secret]
bio:
type: string
birthday:
type: string
format: date
location:
type: object
properties:
province:
type: string
city:
type: string
balance:
type: number
readOnly: true
points:
type: integer
readOnly: true
isRealNameVerified:
type: boolean
readOnly: true
UserUpdate:
type: object
properties:
nickname:
type: string
avatar:
type: string
gender:
type: string
enum: [male, female, secret]
bio:
type: string
birthday:
type: string
format: date
location:
type: object
properties:
province:
type: string
city:
type: string
# --- Content Models ---
ContentItem:
type: object
properties:
id:
type: string
title:
type: string
cover:
type: string
genre:
type: string
type:
type: string
enum: [video, audio, article]
price:
type: number
authorId:
type: string
authorName:
type: string
authorAvatar:
type: string
views:
type: integer
likes:
type: integer
isPurchased:
type: boolean
description: User specific state
ContentDetail:
allOf:
- $ref: '#/components/schemas/ContentItem'
- type: object
properties:
description:
type: string
body:
type: string # HTML/Markdown
mediaUrls:
type: array
items:
type: object
properties:
type:
type: string
url:
type: string
duration:
type: integer
meta:
type: object
properties:
role:
type: string
key:
type: string
beat:
type: string
isLiked:
type: boolean
description: User specific state
isFavorited:
type: boolean
description: User specific state
Comment:
type: object
properties:
id:
type: string
content:
type: string
userId:
type: string
userNickname:
type: string
userAvatar:
type: string
createTime:
type: string
likes:
type: integer
isLiked:
type: boolean
replyTo:
type: string # Comment ID
# --- Tenant/Creator Public Profile ---
TenantProfile:
type: object
properties:
id:
type: string
name:
type: string
avatar:
type: string
cover:
type: string
bio:
type: string
description:
type: string
certType:
type: string
enum: [personal, enterprise]
stats:
type: object
properties:
followers:
type: integer
contents:
type: integer
likes:
type: integer
isFollowing:
type: boolean
# --- Order Models ---
Order:
type: object
properties:
id:
type: string
createTime:
type: string
format: date-time
payTime:
type: string
format: date-time
status:
type: string
enum: [unpaid, paid, completed, refunding, refunded, cancelled]
amount:
type: number
quantity:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/ContentItem'
tenantId:
type: string
tenantName:
type: string
isVirtual:
type: boolean
# --- Creator Dashboard Models ---
CreatorStats:
type: object
properties:
totalFollowers:
type: object
properties:
value:
type: integer
trend:
type: number
description: Percentage change (e.g. 1.2 for +1.2%)
totalRevenue:
type: object
properties:
value:
type: number
trend:
type: number
pendingRefunds:
type: integer
newMessages:
type: integer
PayoutAccount:
type: object
properties:
id:
type: string
type:
type: string
enum: [bank, alipay]
name:
type: string
account:
type: string
realname:
type: string
# --- Upload ---
UploadResult:
type: object
properties:
id:
type: string
url:
type: string
filename:
type: string
size:
type: integer
mimeType:
type: string
security:
- BearerAuth: []
paths:
# ============================
# Public / Auth
# ============================
/auth/otp:
post:
summary: Send OTP
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
phone:
type: string
responses:
'200':
description: OTP sent
/auth/login:
post:
summary: Login or Register with OTP
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
phone:
type: string
otp:
type: string
responses:
'200':
description: Successful login
content:
application/json:
schema:
type: object
properties:
token:
type: string
user:
$ref: '#/components/schemas/User'
# ============================
# Public Content & Interaction
# ============================
/contents:
get:
summary: List contents (Explore / Search)
security: []
parameters:
- name: keyword
in: query
schema:
type: string
description: Search keyword
- name: genre
in: query
schema:
type: string
- name: tenantId
in: query
schema:
type: string
description: Filter by creator
- name: sort
in: query
schema:
type: string
enum: [latest, hot, price_asc]
- name: page
in: query
schema:
type: integer
responses:
'200':
description: List of contents
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ContentItem'
pagination:
$ref: '#/components/schemas/Pagination'
/contents/{id}:
get:
summary: Get content detail
security: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Content detail
content:
application/json:
schema:
$ref: '#/components/schemas/ContentDetail'
/contents/{id}/comments:
get:
summary: Get comments for a content
security: []
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: page
in: query
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
pagination:
$ref: '#/components/schemas/Pagination'
post:
summary: Post a comment
requestBody:
content:
application/json:
schema:
type: object
properties:
content:
type: string
replyTo:
type: string
responses:
'200':
description: Comment created
/comments/{id}/like:
post:
summary: Like a comment
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Liked
/topics:
get:
summary: List curated topics
security: []
responses:
'200':
description: List of topics
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
cover:
type: string
tag:
type: string
count:
type: integer
# ============================
# Public Tenant Profile
# ============================
/tenants/{id}:
get:
summary: Get tenant public profile
security: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TenantProfile'
/tenants/{id}/follow:
post:
summary: Follow a tenant
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Followed
delete:
summary: Unfollow a tenant
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Unfollowed
# ============================
# User Center
# ============================
/me:
get:
summary: Get current user profile
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/User'
put:
summary: Update user profile
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpdate'
responses:
'200':
description: Updated
/me/realname:
post:
summary: Submit real-name authentication
requestBody:
content:
application/json:
schema:
type: object
properties:
realname:
type: string
idCard:
type: string
responses:
'200':
description: Submitted
/me/wallet:
get:
summary: Get wallet balance and transactions
responses:
'200':
content:
application/json:
schema:
type: object
properties:
balance:
type: number
transactions:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
amount:
type: number
type:
type: string
enum: [income, expense]
date:
type: string
/me/wallet/recharge:
post:
summary: Recharge wallet
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
type: number
method:
type: string
enum: [wechat, alipay]
responses:
'200':
description: Recharge initiated
content:
application/json:
schema:
type: object
properties:
payParams:
type: string # QR code or SDK params
orderId:
type: string
/me/orders:
get:
summary: List user orders
parameters:
- name: status
in: query
schema:
type: string
enum: [all, unpaid, completed, refund]
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Order'
/me/orders/{id}:
get:
summary: Get user order detail
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
/me/library:
get:
summary: Get purchased content
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ContentItem'
/me/favorites:
get:
summary: Get favorites
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ContentItem'
post:
summary: Add to favorites
parameters:
- name: contentId
in: query
required: true
schema:
type: string
responses:
'200':
description: Added
/me/favorites/{contentId}:
delete:
summary: Remove from favorites
parameters:
- name: contentId
in: path
required: true
schema:
type: string
responses:
'200':
description: Removed
/me/likes:
get:
summary: Get liked contents
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ContentItem'
post:
summary: Like content
parameters:
- name: contentId
in: query
required: true
schema:
type: string
responses:
'200':
description: Liked
/me/likes/{contentId}:
delete:
summary: Unlike content
parameters:
- name: contentId
in: path
required: true
schema:
type: string
responses:
'200':
description: Unliked
/me/notifications:
get:
summary: Get notifications
parameters:
- name: type
in: query
schema:
type: string
enum: [all, system, order, audit, interaction]
responses:
'200':
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
type:
type: string
title:
type: string
content:
type: string
read:
type: boolean
time:
type: string
# ============================
# Transaction
# ============================
/orders:
post:
summary: Create Order
requestBody:
content:
application/json:
schema:
type: object
properties:
contentId:
type: string
sku:
type: string
quantity:
type: integer
default: 1
responses:
'200':
content:
application/json:
schema:
type: object
properties:
orderId:
type: string
/orders/{id}/pay:
post:
summary: Pay for order
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
method:
type: string
enum: [wechat, alipay, balance]
responses:
'200':
content:
application/json:
schema:
type: object
properties:
payParams:
type: string
/orders/{id}/status:
get:
summary: Check order payment status
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum: [unpaid, paid, completed]
# ============================
# Creator Center
# ============================
/creator/apply:
post:
summary: Apply to become a creator
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
bio:
type: string
avatar:
type: string
responses:
'200':
description: Application submitted
/creator/dashboard:
get:
summary: Get creator dashboard stats
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreatorStats'
/creator/contents:
get:
summary: List creator contents
parameters:
- name: status
in: query
schema:
type: string
- name: genre
in: query
schema:
type: string
- name: keyword
in: query
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ContentItem'
post:
summary: Create/Publish content
requestBody:
content:
application/json:
schema:
type: object
properties:
title:
type: string
genre:
type: string
price:
type: number
mediaIds:
type: array
items:
type: string
responses:
'200':
description: Created
/creator/contents/{id}:
put:
summary: Update content
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
# fields to update
responses:
'200':
description: Updated
delete:
summary: Delete content
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Deleted
/creator/orders:
get:
summary: List sales orders
parameters:
- name: status
in: query
schema:
type: string
- name: keyword
in: query
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Order'
/creator/orders/{id}/refund:
post:
summary: Process refund
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
action:
type: string
enum: [accept, reject]
reason:
type: string
responses:
'200':
description: Processed
/creator/settings:
get:
summary: Get channel settings
responses:
'200':
content:
application/json:
schema:
type: object
properties:
name:
type: string
bio:
type: string
avatar:
type: string
cover:
type: string
description:
type: string
put:
summary: Update channel settings
requestBody:
content:
application/json:
schema:
type: object
# fields to update
responses:
'200':
description: Updated
/creator/payout-accounts:
get:
summary: List payout accounts
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PayoutAccount'
post:
summary: Add payout account
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutAccount'
responses:
'200':
description: Added
delete:
summary: Remove payout account
parameters:
- name: id
in: query
required: true
schema:
type: string
responses:
'200':
description: Removed
/creator/withdraw:
post:
summary: Request withdrawal
requestBody:
content:
application/json:
schema:
type: object
properties:
amount:
type: number
method:
type: string
enum: [wallet, external]
accountId:
type: string # Required if method is external
responses:
'200':
description: Withdrawal requested
# ============================
# Common / Upload
# ============================
/upload:
post:
summary: Upload file
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
type:
type: string
enum: [image, video, audio]
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UploadResult'