895 lines
24 KiB
YAML
895 lines
24 KiB
YAML
basePath: /api/v1
|
|
definitions:
|
|
data.EventIndexDoc:
|
|
properties:
|
|
description:
|
|
type: string
|
|
end_time:
|
|
type: string
|
|
event_id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
start_time:
|
|
type: string
|
|
thumbnail:
|
|
type: string
|
|
type:
|
|
type: string
|
|
type: object
|
|
data.UserIndexDoc:
|
|
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
|
|
service_auth.ExchangeData:
|
|
properties:
|
|
client_id:
|
|
type: string
|
|
redirect_uri:
|
|
type: string
|
|
state:
|
|
type: string
|
|
type: object
|
|
service_auth.ExchangeResponse:
|
|
properties:
|
|
redirect_uri:
|
|
type: string
|
|
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.MagicResponse:
|
|
properties:
|
|
uri:
|
|
type: string
|
|
type: object
|
|
service_auth.RefreshData:
|
|
properties:
|
|
refresh_token:
|
|
type: string
|
|
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_event.CheckinQueryResponse:
|
|
properties:
|
|
checkin_at:
|
|
type: string
|
|
type: object
|
|
service_event.CheckinResponse:
|
|
properties:
|
|
checkin_code:
|
|
type: string
|
|
type: object
|
|
service_event.CheckinSubmitData:
|
|
properties:
|
|
checkin_code:
|
|
type: string
|
|
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
|
|
utils.RespStatus:
|
|
properties:
|
|
code:
|
|
type: integer
|
|
data: {}
|
|
error_id:
|
|
type: string
|
|
status:
|
|
type: string
|
|
type: object
|
|
host: localhost:8000
|
|
info:
|
|
contact:
|
|
email: support@swagger.io
|
|
name: API Support
|
|
url: http://www.swagger.io/support
|
|
description: API Docs based on Gin framework
|
|
license:
|
|
name: Apache 2.0
|
|
url: http://www.apache.org/licenses/LICENSE-2.0.html
|
|
termsOfService: http://swagger.io/terms/
|
|
title: NixCN CMS API
|
|
version: "1.0"
|
|
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: Successful exchange
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_auth.ExchangeResponse'
|
|
type: object
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
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: Successful request
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_auth.MagicResponse'
|
|
type: object
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"403":
|
|
description: Turnstile Verification Failed
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
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:
|
|
- application/json
|
|
- 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:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"403":
|
|
description: Invalid or Expired Verification Code
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
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: Successful rotation
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_auth.TokenResponse'
|
|
type: object
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Invalid Refresh Token
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
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: Successful token issuance
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_auth.TokenResponse'
|
|
type: object
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"403":
|
|
description: Invalid or Expired Code
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
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: Successfully generated code
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_event.CheckinResponse'
|
|
type: object
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
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: Current attendance status
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_event.CheckinQueryResponse'
|
|
type: object
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"404":
|
|
description: Record Not Found
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
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: Attendance marked successfully
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid Code or Input
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
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: Successful retrieval
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/data.EventIndexDoc'
|
|
type: object
|
|
"400":
|
|
description: Invalid Input
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"404":
|
|
description: Event Not Found
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: Get Event Information
|
|
tags:
|
|
- Event
|
|
/event/list:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Fetches a list of events with support for pagination via limit
|
|
and offset. Data is retrieved directly from the database for consistency.
|
|
parameters:
|
|
- description: Maximum number of events to return (default 20)
|
|
in: query
|
|
name: limit
|
|
type: string
|
|
- description: Number of events to skip
|
|
in: query
|
|
name: offset
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Successful paginated list retrieval
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
items:
|
|
$ref: '#/definitions/data.EventIndexDoc'
|
|
type: array
|
|
type: object
|
|
"400":
|
|
description: Invalid Input (Missing offset or malformed parameters)
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error (Database query failed)
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: List Events
|
|
tags:
|
|
- Event
|
|
/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: Successful profile retrieval
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_user.UserInfoData'
|
|
type: object
|
|
"403":
|
|
description: Missing User ID / Unauthorized
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"404":
|
|
description: User Not Found
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error (UUID Parse Failed)
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: Get My User Information
|
|
tags:
|
|
- User
|
|
/user/info/{user_id}:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Fetches the complete profile data for the user associated with
|
|
the provided session/token.
|
|
parameters:
|
|
- description: Other user id
|
|
in: path
|
|
name: user_id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Successful profile retrieval
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_user.UserInfoData'
|
|
type: object
|
|
"403":
|
|
description: Missing User ID / Unauthorized
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"404":
|
|
description: User Not Public
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/service_user.UserInfoData'
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error (UUID Parse Failed)
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: Get Other User Information
|
|
tags:
|
|
- User
|
|
/user/list:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Fetches a list of users with support for pagination via limit and
|
|
offset. Data is sourced from the search engine for high performance.
|
|
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: Successful paginated list retrieval
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
items:
|
|
$ref: '#/definitions/data.UserIndexDoc'
|
|
type: array
|
|
type: object
|
|
"400":
|
|
description: Invalid Input (Format Error)
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error (Search Engine or Missing Offset)
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
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: Successful profile update
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid Input (Validation Failed)
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"403":
|
|
description: Missing User ID / Unauthorized
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error (Database Error / UUID Parse Failed)
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/utils.RespStatus'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
security:
|
|
- ApiKeyAuth: []
|
|
summary: Update User Information
|
|
tags:
|
|
- User
|
|
schemes:
|
|
- http
|
|
- https
|
|
swagger: "2.0"
|