docs: add openapi specification
This commit is contained in:
480
internal/api/openapi.yaml
Normal file
480
internal/api/openapi.yaml
Normal file
@@ -0,0 +1,480 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Minecraft Platform API
|
||||
description: API for Minecraft Server Platform handling auth, skins, modpacks, and servers.
|
||||
version: 1.0.0
|
||||
servers:
|
||||
- url: http://localhost:8080
|
||||
description: Local development server
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
|
||||
security:
|
||||
- bearerAuth: []
|
||||
|
||||
paths:
|
||||
# --- Public Auth & User Registration ---
|
||||
/api/register:
|
||||
post:
|
||||
summary: Register a new user
|
||||
tags: [Auth]
|
||||
security: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [username, email, password]
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
password:
|
||||
type: string
|
||||
format: password
|
||||
responses:
|
||||
201:
|
||||
description: User registered successfully
|
||||
400:
|
||||
description: Validation error
|
||||
|
||||
/api/login:
|
||||
post:
|
||||
summary: Login user
|
||||
tags: [Auth]
|
||||
security: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [email, password]
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
password:
|
||||
type: string
|
||||
format: password
|
||||
responses:
|
||||
200:
|
||||
description: Login successful
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
user:
|
||||
$ref: '#/components/schemas/User'
|
||||
401:
|
||||
description: Invalid credentials
|
||||
|
||||
# --- Auth Server (Launcher Integration) ---
|
||||
/authserver/authenticate:
|
||||
post:
|
||||
summary: Authenticate (Launcher flow)
|
||||
tags: [Auth]
|
||||
security: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
username:
|
||||
type: string
|
||||
password:
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: Authenticated
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
accessToken:
|
||||
type: string
|
||||
clientToken:
|
||||
type: string
|
||||
selectedProfile:
|
||||
$ref: '#/components/schemas/GameProfile'
|
||||
|
||||
# --- Session Server ---
|
||||
/sessionserver/session/minecraft/join:
|
||||
post:
|
||||
summary: Join server (Client-side)
|
||||
tags: [Auth]
|
||||
security: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
accessToken:
|
||||
type: string
|
||||
selectedProfile:
|
||||
type: string
|
||||
serverId:
|
||||
type: string
|
||||
responses:
|
||||
204:
|
||||
description: Joined successfully
|
||||
|
||||
/sessionserver/session/minecraft/profile/{uuid}:
|
||||
get:
|
||||
summary: Get user profile (Server-side check)
|
||||
tags: [User]
|
||||
security: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: uuid
|
||||
schema:
|
||||
type: string
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
description: Profile data
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GameProfile'
|
||||
|
||||
# --- User Endpoints ---
|
||||
/api/user/me:
|
||||
get:
|
||||
summary: Get current user info
|
||||
tags: [User]
|
||||
responses:
|
||||
200:
|
||||
description: Current user
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
|
||||
/api/user/skin:
|
||||
post:
|
||||
summary: Upload skin
|
||||
tags: [User]
|
||||
requestBody:
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
responses:
|
||||
200:
|
||||
description: Skin uploaded
|
||||
|
||||
# --- Servers ---
|
||||
/api/servers:
|
||||
get:
|
||||
summary: Get game servers list
|
||||
tags: [Servers]
|
||||
security: []
|
||||
responses:
|
||||
200:
|
||||
description: List of servers
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/GameServer'
|
||||
|
||||
# --- Launcher ---
|
||||
/api/launcher/modpacks/summary:
|
||||
get:
|
||||
summary: Get modpacks summary (for launcher)
|
||||
tags: [Launcher]
|
||||
security: []
|
||||
responses:
|
||||
200:
|
||||
description: List of modpacks
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
/api/launcher/modpacks/{name}/manifest:
|
||||
get:
|
||||
summary: Get modpack manifest
|
||||
tags: [Launcher]
|
||||
security: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: name
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: Modpack manifest
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
path:
|
||||
type: string
|
||||
hash:
|
||||
type: string
|
||||
size:
|
||||
type: integer
|
||||
|
||||
# --- Admin / Modpacks ---
|
||||
/api/admin/modpacks:
|
||||
get:
|
||||
summary: Get all modpacks (Admin)
|
||||
tags: [Admin]
|
||||
responses:
|
||||
200:
|
||||
description: List of full modpack details
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Modpack'
|
||||
|
||||
/api/admin/modpacks/import:
|
||||
post:
|
||||
summary: Import new modpack
|
||||
tags: [Admin]
|
||||
requestBody:
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
displayName:
|
||||
type: string
|
||||
mcVersion:
|
||||
type: string
|
||||
importerType:
|
||||
type: string
|
||||
enum: [simple, curseforge, modrinth]
|
||||
importMethod:
|
||||
type: string
|
||||
enum: [file, url]
|
||||
sourceUrl:
|
||||
type: string
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
responses:
|
||||
202:
|
||||
description: Job started
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
job_id:
|
||||
type: integer
|
||||
message:
|
||||
type: string
|
||||
|
||||
/api/admin/modpacks/update:
|
||||
post:
|
||||
summary: Update existing modpack
|
||||
tags: [Admin]
|
||||
requestBody:
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
modpackName:
|
||||
type: string
|
||||
mcVersion:
|
||||
type: string
|
||||
importerType:
|
||||
type: string
|
||||
importMethod:
|
||||
type: string
|
||||
sourceUrl:
|
||||
type: string
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
responses:
|
||||
202:
|
||||
description: Job started
|
||||
|
||||
/api/admin/modpacks/versions:
|
||||
get:
|
||||
summary: Get modpack versions (CurseForge)
|
||||
tags: [Admin]
|
||||
parameters:
|
||||
- in: query
|
||||
name: url
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
200:
|
||||
description: List of versions
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
file_id:
|
||||
type: integer
|
||||
display_name:
|
||||
type: string
|
||||
game_versions:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
|
||||
# --- Admin / Users ---
|
||||
/api/admin/users:
|
||||
get:
|
||||
summary: Get all users
|
||||
tags: [Admin]
|
||||
responses:
|
||||
200:
|
||||
description: List of users
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/User'
|
||||
|
||||
/api/admin/users/{id}/role:
|
||||
patch:
|
||||
summary: Update user role
|
||||
tags: [Admin]
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
role:
|
||||
type: string
|
||||
enum: [user, admin]
|
||||
responses:
|
||||
200:
|
||||
description: Role updated
|
||||
|
||||
components:
|
||||
schemas:
|
||||
User:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
username:
|
||||
type: string
|
||||
email:
|
||||
type: string
|
||||
role:
|
||||
type: string
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
|
||||
GameProfile:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
properties:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
value:
|
||||
type: string
|
||||
signature:
|
||||
type: string
|
||||
|
||||
GameServer:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
name:
|
||||
type: string
|
||||
address:
|
||||
type: string
|
||||
is_enabled:
|
||||
type: boolean
|
||||
motd:
|
||||
type: string
|
||||
player_count:
|
||||
type: integer
|
||||
max_players:
|
||||
type: integer
|
||||
version_name:
|
||||
type: string
|
||||
ping_proxy_server:
|
||||
type: integer
|
||||
bluemap_url:
|
||||
type: string
|
||||
|
||||
Modpack:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
name:
|
||||
type: string
|
||||
display_name:
|
||||
type: string
|
||||
minecraft_version:
|
||||
type: string
|
||||
is_active:
|
||||
type: boolean
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
Reference in New Issue
Block a user