Files
persionalBrand/docs/openapi.yaml
T
2026-09-19 18:46:26 +08:00

350 lines
10 KiB
YAML

openapi: 3.1.0
info:
title: Personal Brand API
version: 0.1.0
description: 单品牌个人经营者小程序与管理后台 API。
servers:
- url: http://localhost:3001
paths:
/health:
get:
operationId: getHealth
responses:
"200":
description: API health status
content:
application/json:
schema:
$ref: "#/components/schemas/Health"
/public/brand:
get:
operationId: getPublicBrand
responses:
"200":
description: Public brand profile
content:
application/json:
schema:
$ref: "#/components/schemas/BrandProfile"
/public/services:
get:
operationId: listPublicServices
responses:
"200":
description: Enabled public services
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PublicService"
/customer/session/wechat:
post:
operationId: createCustomerSession
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [code]
properties:
code:
type: string
responses:
"201":
description: Customer session token
content:
application/json:
schema:
$ref: "#/components/schemas/TokenResponse"
/customer/bookings:
get:
operationId: listCustomerBookings
security: [bearerAuth: []]
responses:
"200":
description: Current customer's bookings
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Booking"
post:
operationId: createCustomerBooking
security: [bearerAuth: []]
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateBooking"
responses:
"201":
description: Created booking summary
content:
application/json:
schema:
$ref: "#/components/schemas/BookingSummary"
/customer/bookings/{id}/cancel:
post:
operationId: cancelCustomerBooking
security: [bearerAuth: []]
parameters:
- $ref: "#/components/parameters/BookingId"
responses:
"201":
description: Cancelled booking
content:
application/json:
schema:
$ref: "#/components/schemas/Booking"
/admin/session/login:
post:
operationId: createAdminSession
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AdminLogin"
responses:
"201":
description: Admin session token
content:
application/json:
schema:
$ref: "#/components/schemas/AdminTokenResponse"
/admin/bookings:
get:
operationId: listAdminBookings
security: [bearerAuth: []]
parameters:
- in: query
name: status
schema:
$ref: "#/components/schemas/BookingStatus"
- in: query
name: unreadOnly
schema:
type: boolean
- in: query
name: tagId
schema:
type: string
responses:
"200":
description: Admin booking list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Booking"
/admin/bookings/unread-count:
get:
operationId: getAdminUnreadBookingCount
security: [bearerAuth: []]
responses:
"200":
description: Number of unread bookings
content:
application/json:
schema:
type: object
required: [count]
properties:
count: { type: integer, minimum: 0 }
/admin/bookings/{id}:
get:
operationId: getAdminBooking
security: [bearerAuth: []]
parameters:
- $ref: "#/components/parameters/BookingId"
responses:
"200":
description: Admin booking detail
content:
application/json:
schema:
$ref: "#/components/schemas/Booking"
/admin/bookings/{id}/status:
post:
operationId: updateAdminBookingStatus
security: [bearerAuth: []]
parameters:
- $ref: "#/components/parameters/BookingId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateBookingStatus"
responses:
"201":
description: Updated booking
content:
application/json:
schema:
$ref: "#/components/schemas/Booking"
/admin/bookings/{id}/read:
post:
operationId: markAdminBookingRead
security: [bearerAuth: []]
parameters:
- $ref: "#/components/parameters/BookingId"
responses:
"201":
description: Updated booking
/admin/bookings/tags:
get:
operationId: listAdminTags
security: [bearerAuth: []]
responses:
"200":
description: Enabled tags
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Tag"
post:
operationId: createAdminTag
security: [bearerAuth: []]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name]
properties:
name: { type: string, maxLength: 24 }
responses:
"201":
description: Created tag
content:
application/json:
schema:
$ref: "#/components/schemas/Tag"
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
parameters:
BookingId:
in: path
name: id
required: true
schema: { type: string, format: uuid }
schemas:
Health:
type: object
required: [status, service]
properties:
status: { type: string, example: ok }
service: { type: string, example: personal-brand-api }
BrandProfile:
type: object
required: [id, name]
properties:
id: { type: string, format: uuid }
name: { type: string }
tagline: { type: [string, "null"] }
description: { type: [string, "null"] }
avatarUrl: { type: [string, "null"], format: uri }
coverUrl: { type: [string, "null"], format: uri }
hours: { type: [string, "null"] }
address: { type: [string, "null"] }
deliveryNote: { type: [string, "null"] }
PublicService:
type: object
required: [id, name, description, bookingEnabled]
properties:
id: { type: string, format: uuid }
name: { type: string }
description: { type: string }
coverUrl: { type: [string, "null"], format: uri }
priceText: { type: [string, "null"] }
priceAmount: { type: [integer, "null"], minimum: 0 }
bookingEnabled: { type: boolean }
BookingStatus:
type: string
enum: [received, contacting, confirmed, completed, cancelled]
BookingItemInput:
type: object
required: [serviceId, quantity]
properties:
serviceId: { type: string, format: uuid }
quantity: { type: integer, minimum: 1, maximum: 50 }
CreateBooking:
type: object
required: [requestType, customerName, contactPreference, items]
properties:
requestType: { type: string, enum: [package, private_chef] }
customerName: { type: string }
phone: { type: string }
wechatId: { type: string }
contactPreference: { type: string, enum: [wechat, phone, none] }
fulfillmentType: { type: string, enum: [pickup, delivery] }
serviceId: { type: string, format: uuid }
requestedDate: { type: string, format: date-time }
requestedTime: { type: string }
deliveryAddress: { type: string }
note: { type: string }
extraData: { type: object, additionalProperties: true }
items:
type: array
items: { $ref: "#/components/schemas/BookingItemInput" }
BookingSummary:
type: object
required: [bookingNo, status, estimatedAmount, createdAt]
properties:
bookingNo: { type: string }
status: { $ref: "#/components/schemas/BookingStatus" }
estimatedAmount: { type: [integer, "null"] }
createdAt: { type: string, format: date-time }
Booking:
allOf:
- $ref: "#/components/schemas/BookingSummary"
- type: object
properties:
id: { type: string, format: uuid }
customerName: { type: string }
adminNote: { type: [string, "null"] }
AdminLogin:
type: object
required: [username, password]
properties:
username: { type: string }
password: { type: string, format: password }
TokenResponse:
type: object
required: [token]
properties:
token: { type: string }
AdminTokenResponse:
allOf:
- $ref: "#/components/schemas/TokenResponse"
- type: object
required: [displayName]
properties:
displayName: { type: string }
UpdateBookingStatus:
type: object
required: [status]
properties:
status: { $ref: "#/components/schemas/BookingStatus" }
adminNote: { type: string }
Tag:
type: object
required: [id, name, isEnabled]
properties:
id: { type: string, format: uuid }
name: { type: string }
isPreset: { type: boolean }
isEnabled: { type: boolean }