docs: add openapi specification

internal/api/openapi.yaml

@@ -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