647 lines
16 KiB
YAML
647 lines
16 KiB
YAML
definitions:
|
|
data.User:
|
|
properties:
|
|
allow_public:
|
|
type: boolean
|
|
avatar:
|
|
type: string
|
|
bio:
|
|
type: string
|
|
email:
|
|
type: string
|
|
id:
|
|
type: integer
|
|
nickname:
|
|
type: string
|
|
permission_level:
|
|
type: integer
|
|
subtitle:
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
username:
|
|
type: string
|
|
uuid:
|
|
type: string
|
|
type: object
|
|
data.UserSearchDoc:
|
|
properties:
|
|
avatar:
|
|
type: string
|
|
email:
|
|
type: string
|
|
nickname:
|
|
type: string
|
|
subtitle:
|
|
type: string
|
|
type:
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
username:
|
|
type: string
|
|
type: object
|
|
exception.Builder:
|
|
properties:
|
|
endpoint:
|
|
type: string
|
|
error: {}
|
|
errorCode:
|
|
type: string
|
|
original:
|
|
type: string
|
|
service:
|
|
type: string
|
|
status:
|
|
type: string
|
|
type:
|
|
type: string
|
|
type: object
|
|
service_auth.ExchangeData:
|
|
properties:
|
|
client_id:
|
|
type: string
|
|
redirect_uri:
|
|
type: string
|
|
state:
|
|
type: string
|
|
type: object
|
|
service_auth.ExchangeResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
data:
|
|
properties:
|
|
redirect_uri:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
service_auth.MagicData:
|
|
properties:
|
|
client_id:
|
|
type: string
|
|
client_ip:
|
|
type: string
|
|
email:
|
|
type: string
|
|
redirect_uri:
|
|
type: string
|
|
state:
|
|
type: string
|
|
turnstile_token:
|
|
type: string
|
|
type: object
|
|
service_auth.MagicResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
data: {}
|
|
type: object
|
|
service_auth.RefreshData:
|
|
properties:
|
|
refresh_token:
|
|
type: string
|
|
type: object
|
|
service_auth.RefreshResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
data:
|
|
$ref: '#/definitions/service_auth.TokenResponse'
|
|
type: object
|
|
service_auth.TokenData:
|
|
properties:
|
|
code:
|
|
type: string
|
|
type: object
|
|
service_auth.TokenResponse:
|
|
properties:
|
|
access_token:
|
|
type: string
|
|
refresh_token:
|
|
type: string
|
|
type: object
|
|
service_auth.TokenResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
data:
|
|
$ref: '#/definitions/service_auth.TokenResponse'
|
|
type: object
|
|
service_event.CheckinQueryResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
data:
|
|
properties:
|
|
checkin_at:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
service_event.CheckinResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
data:
|
|
properties:
|
|
checkin_code:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
service_event.CheckinSubmitData:
|
|
properties:
|
|
checkin_code:
|
|
type: string
|
|
type: object
|
|
service_event.CheckinSubmitResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
type: object
|
|
service_event.InfoResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
data:
|
|
properties:
|
|
end_time:
|
|
type: string
|
|
name:
|
|
type: string
|
|
start_time:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
service_user.UserInfoData:
|
|
properties:
|
|
allow_public:
|
|
type: boolean
|
|
avatar:
|
|
type: string
|
|
bio:
|
|
type: string
|
|
email:
|
|
type: string
|
|
nickname:
|
|
type: string
|
|
permission_level:
|
|
type: integer
|
|
subtitle:
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
username:
|
|
type: string
|
|
type: object
|
|
service_user.UserInfoResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
data:
|
|
$ref: '#/definitions/service_user.UserInfoData'
|
|
type: object
|
|
service_user.UserListResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
user_list:
|
|
items:
|
|
$ref: '#/definitions/data.UserSearchDoc'
|
|
type: array
|
|
type: object
|
|
service_user.UserTableResult:
|
|
properties:
|
|
common:
|
|
$ref: '#/definitions/shared.CommonResult'
|
|
user_table:
|
|
items:
|
|
$ref: '#/definitions/data.User'
|
|
type: array
|
|
type: object
|
|
shared.CommonResult:
|
|
properties:
|
|
exception:
|
|
$ref: '#/definitions/exception.Builder'
|
|
httpCode:
|
|
type: integer
|
|
type: object
|
|
info:
|
|
contact: {}
|
|
paths:
|
|
/auth/exchange:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Exchanges client credentials and user session for a specific redirect
|
|
authorization code.
|
|
parameters:
|
|
- description: Exchange Request Credentials
|
|
in: body
|
|
name: payload
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/service_auth.ExchangeData'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_auth.ExchangeResult'
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
type: string
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
type: string
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: Exchange Auth Code
|
|
tags:
|
|
- Authentication
|
|
/auth/magic:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Verifies Turnstile token and sends an authentication link via email.
|
|
Returns the URI directly if debug mode is enabled.
|
|
parameters:
|
|
- description: Magic Link Request Data
|
|
in: body
|
|
name: payload
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/service_auth.MagicData'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_auth.MagicResult'
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
type: string
|
|
"403":
|
|
description: Turnstile Verification Failed
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
type: string
|
|
summary: Request Magic Link
|
|
tags:
|
|
- Authentication
|
|
/auth/redirect:
|
|
get:
|
|
consumes:
|
|
- application/x-www-form-urlencoded
|
|
description: Verifies the temporary email code, ensures the user exists (or
|
|
creates one), validates the client's redirect URI, and finally performs a
|
|
302 redirect with a new authorization code.
|
|
parameters:
|
|
- description: Client Identifier
|
|
in: query
|
|
name: client_id
|
|
required: true
|
|
type: string
|
|
- description: Target Redirect URI
|
|
in: query
|
|
name: redirect_uri
|
|
required: true
|
|
type: string
|
|
- description: Temporary Verification Code
|
|
in: query
|
|
name: code
|
|
required: true
|
|
type: string
|
|
- description: Opaque state used to maintain state between the request and callback
|
|
in: query
|
|
name: state
|
|
type: string
|
|
produces:
|
|
- text/html
|
|
responses:
|
|
"302":
|
|
description: Redirect to the provided RedirectUri with a new code
|
|
schema:
|
|
type: string
|
|
"400":
|
|
description: Invalid Input / Client Not Found / URI Mismatch
|
|
schema:
|
|
type: string
|
|
"403":
|
|
description: Invalid or Expired Verification Code
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
type: string
|
|
summary: Handle Auth Callback and Redirect
|
|
tags:
|
|
- Authentication
|
|
/auth/refresh:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Accepts a valid refresh token to issue a new access token and a
|
|
rotated refresh token.
|
|
parameters:
|
|
- description: Refresh Token Body
|
|
in: body
|
|
name: payload
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/service_auth.RefreshData'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_auth.RefreshResult'
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
type: string
|
|
"401":
|
|
description: Invalid Refresh Token
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
type: string
|
|
summary: Refresh Access Token
|
|
tags:
|
|
- Authentication
|
|
/auth/token:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Verifies the provided authorization code and issues a pair of JWT
|
|
tokens (Access and Refresh).
|
|
parameters:
|
|
- description: Token Request Body
|
|
in: body
|
|
name: payload
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/service_auth.TokenData'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_auth.TokenResult'
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
type: string
|
|
"403":
|
|
description: Invalid or Expired Code
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
type: string
|
|
summary: Exchange Code for Token
|
|
tags:
|
|
- Authentication
|
|
/event/checkin:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Creates a temporary check-in code for the authenticated user and
|
|
event.
|
|
parameters:
|
|
- description: Event UUID
|
|
in: query
|
|
name: event_id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_event.CheckinResult'
|
|
summary: Generate Check-in Code
|
|
tags:
|
|
- Event
|
|
/event/checkin/query:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Returns the timestamp of when the user checked in, or null if not
|
|
yet checked in.
|
|
parameters:
|
|
- description: Event UUID
|
|
in: query
|
|
name: event_id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_event.CheckinQueryResult'
|
|
summary: Query Check-in Status
|
|
tags:
|
|
- Event
|
|
/event/checkin/submit:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Submits the generated code to mark the user as attended.
|
|
parameters:
|
|
- description: Checkin Code Data
|
|
in: body
|
|
name: payload
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/service_event.CheckinSubmitData'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_event.CheckinSubmitResult'
|
|
summary: Submit Check-in Code
|
|
tags:
|
|
- Event
|
|
/event/info:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Fetches the name, start time, and end time of an event using its
|
|
UUID.
|
|
parameters:
|
|
- description: Event UUID
|
|
in: query
|
|
name: event_id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_event.InfoResult'
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: Event Not Found
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
type: string
|
|
summary: Get Event Information
|
|
tags:
|
|
- Event
|
|
/user/full:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Fetches all user records without pagination. This is typically
|
|
used for administrative overview or data export.
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_user.UserTableResult'
|
|
"500":
|
|
description: Internal Server Error (Database Error)
|
|
schema:
|
|
type: string
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: Get Full User Table
|
|
tags:
|
|
- User
|
|
/user/info:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Fetches the complete profile data for the user associated with
|
|
the provided session/token.
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_user.UserInfoResult'
|
|
"403":
|
|
description: Missing User ID / Unauthorized
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: User Not Found
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error (UUID Parse Failed)
|
|
schema:
|
|
type: string
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: Get My User Information
|
|
tags:
|
|
- User
|
|
/user/list:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Fetches a list of users with support for pagination via limit and
|
|
offset.
|
|
parameters:
|
|
- description: Maximum number of users to return (default 0)
|
|
in: query
|
|
name: limit
|
|
type: string
|
|
- description: Number of users to skip
|
|
in: query
|
|
name: offset
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_user.UserListResult'
|
|
"400":
|
|
description: Invalid Input (Format Error)
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error (Search Engine or Missing Offset)
|
|
schema:
|
|
type: string
|
|
summary: List Users
|
|
tags:
|
|
- User
|
|
/user/update:
|
|
patch:
|
|
consumes:
|
|
- application/json
|
|
description: |-
|
|
Updates specific profile fields such as username, nickname, subtitle, avatar (URL), and bio (Base64).
|
|
Validation: Username (5-255 chars), Nickname (max 24 chars), Subtitle (max 32 chars).
|
|
parameters:
|
|
- description: Updated User Profile Data
|
|
in: body
|
|
name: payload
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/service_user.UserInfoData'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/service_user.UserInfoResult'
|
|
"400":
|
|
description: Invalid Input (Validation Failed)
|
|
schema:
|
|
type: string
|
|
"403":
|
|
description: Missing User ID / Unauthorized
|
|
schema:
|
|
type: string
|
|
"500":
|
|
description: Internal Server Error (Database Error / UUID Parse Failed)
|
|
schema:
|
|
type: string
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: Update User Information
|
|
tags:
|
|
- User
|
|
swagger: "2.0"
|