Full Restruct API and Services
Some checks failed
Backend Check Build (NixCN CMS) TeamCity build failed
Client CMS Check Build (NixCN CMS) TeamCity build finished

Signed-off-by: Asai Neko <sugar@sne.moe>
This commit is contained in:
2026-01-29 00:45:58 +08:00
parent 89e7f1a41a
commit 79dfa8499c
27 changed files with 4011 additions and 21 deletions

979
docs/swagger.json Normal file
View File

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