Files
persionalBrand/docs/openapi.yaml

406 lines
12 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/offerings:
get:
operationId: listPublicOfferings
responses:
"200":
description: Enabled public services
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PublicOffering"
/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/session/logout:
post:
operationId: logoutCustomer
security: [bearerAuth: []]
responses:
"201":
description: Customer session revoked
content:
application/json:
schema:
$ref: "#/components/schemas/LoggedOut"
/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 created; the access token is set as an HttpOnly cookie
content:
application/json:
schema:
$ref: "#/components/schemas/AdminLoginSession"
/admin/session/current:
get:
operationId: getAdminSession
security:
- cookieAuth: []
- bearerAuth: []
responses:
"200":
description: Current admin session
content:
application/json:
schema:
$ref: "#/components/schemas/AdminSession"
/admin/session/logout:
post:
operationId: logoutAdmin
security:
- cookieAuth: []
- bearerAuth: []
responses:
"201":
description: Admin session revoked
content:
application/json:
schema:
$ref: "#/components/schemas/LoggedOut"
/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
cookieAuth:
type: apiKey
in: cookie
name: admin_session
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"] }
PublicOffering:
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 }
LoggedOut:
type: object
required: [loggedOut]
properties:
loggedOut: { type: boolean, enum: [true] }
AdminSession:
type: object
required: [authenticated, displayName, mustChangePassword, role, platformTemplateRole]
properties:
authenticated: { type: boolean, enum: [true] }
displayName: { type: string }
mustChangePassword: { type: boolean }
role: { type: string }
platformTemplateRole: { type: string, enum: [none, template_admin] }
AdminLoginSession:
type: object
required: [displayName, mustChangePassword, role, platformTemplateRole]
properties:
displayName: { type: string }
mustChangePassword: { type: boolean }
role: { type: string }
platformTemplateRole: { type: string, enum: [none, template_admin] }
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 }