Server/api/api.yml

openapi: 3.0.0
info:
  title: Tower Defence Server
  description: An API for talking to the Tower Defence Server
  version: 0.0.1
servers:
  - url: /api/v1
  - url: http://localhost:8080/api/v1
security:
  - JWTAuth: []

components:
  securitySchemes:
    JWTAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    #############################################
    #  UUID                                     #
    #############################################
    UUID:
      description: Unique identifier compatible with [RFC9562](https://datatracker.ietf.org/doc/html/rfc9562)
      type: string
      format: uuid
      example: f0981749-f550-46cd-b9ce-b6ca7cd0251f
    #############################################
    #  PlayerRegistrationData                   #
    #############################################
    PlayerRegistrationData:
      description: Data needed to create a new player
      type: object
      properties:
        username:
          type: string
        password:
          type: string
      required:
        - username
        - password
    #############################################
    #  AdminAuthInfo                            #
    #############################################
    ServerHealth:
      type: object
      properties:
        okay:
          type: boolean
      required:
        - okay
    #############################################
    #  AdminAuthInfo                            #
    #############################################
    AdminAuthInfo:
      type: object
      properties:
        username:
           type: string
      required:
        - username
    #############################################
    #  PlayerApiModel                                   #
    #############################################
    PlayerApiModel:
      description: a Player
      type: object
      properties:
        username:
          type: string
      required:
        - username
  responses:
    201PlayerCreated:
      description: "201 - Player Created"
    401Unauthorized:
      description: "401 - Unauthorized"
    404NotFound:
      description: "Not Found"
      content:
        text/plain:
          schema:
            type: string
    409UsernameTaken:
      description: "409 - Username Taken"
      content:
        text/plain:
          schema:
            type: string
    409Conflict:
      description: "409 - Conflict"
      content:
        text/plain:
          schema:
            type: string
    500InternalError:
      description: "500 - Internal Server Error"
      content:
        text/plain:
          schema:
            type: string
    503ServiceUnavailable:
      description: "503 - Service Unavailable"
      content:
        text/plain:
          schema:
            type: string
paths:
  /player/register:
    post:
      operationId: "PlayerRegister"
      tags:
        - server
      description: "Endpoint for registering a new Player"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlayerRegistrationData"
      responses:
        201:
          $ref: "#/components/responses/201PlayerCreated"
        409:
          $ref: "#/components/responses/409UsernameTaken"
        500:
          $ref: "#/components/responses/500InternalError"
  /server/health:
    get:
      operationId: "ServerGetHealthcheck"
      tags:
        - server
      description: "Endpoint for doing a Healthcheck of the Server"
      responses:
        200:
          description: "A Health-Report of the server"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerHealth"
        500:
          $ref: "#/components/responses/500InternalError"
        503:
          $ref: "#/components/responses/503ServiceUnavailable"
  /admin/authenticated:
    get:
      operationId: "AdminGetAuthenticated"
      tags:
        - admin
      description: "Endpoint for Checking if you're authenticated as an admin"
      responses:
        200:
          description: "A Minimal Admin Info for testing if the admin is logged in"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminAuthInfo"
        401:
          $ref: "#/components/responses/401Unauthorized"
        500:
          $ref: "#/components/responses/500InternalError"
        503:
          $ref: "#/components/responses/503ServiceUnavailable"
  /admin/players:
    get:
      operationId: "GetAllPlayers"
      summary: "Retrieve a paginated list of players"
      description: "Returns a paginated list of players, optionally filtered by username."
      parameters:
        - name: page
          in: query
          description: "Page number (zero-based index)."
          required: false
          schema:
            type: integer
            default: 0
        - name: pageSize
          in: query
          description: "Number of players per page."
          required: false
          schema:
            type: integer
            default: 10
        - name: sortBy
          in: query
          description: "Field to sort by (default is username)."
          required: false
          schema:
            type: string
            default: "username"
        - name: order
          in: query
          description: "Sorting order (asc or desc)."
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: "asc"
        - name: username
          in: query
          description: "Filter players by username (case-insensitive, partial match)."
          required: false
          schema:
            type: string
      tags:
        - admin
      responses:
        200:
          description: "A List of all Player"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PlayerApiModel"
        401:
          $ref: "#/components/responses/401Unauthorized"
        500:
          $ref: "#/components/responses/500InternalError"
        503:
          $ref: "#/components/responses/503ServiceUnavailable"