openapi.yml

# ******************************************************************************
# * Copyright (c) 2023 DevCloud Software. All Rights reserved.
# ******************************************************************************

openapi: "3.0.0"
info:
  title: BetterAPI
  description: BetterAPI Minecraft API Dokumentation.
  version: 1.0.2
  contact:
    name: Dev-Cloud Software
    email: contact@dev-cloud.software
    url: https://dev-cloud.software/
servers:
  - url: http:{host}:{port}/{suffix}
    variables:
      host:
        default: localhost
        description: The IP-Address od the API-Endpoint
      port:
        default: '8080'
      suffix:
        default: api

paths:
  /players/list:
    get:
      tags:
        - Players
      operationId: listPlayers
      description: This returns an array of playerObjects
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/playerList'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/generalError'
  /player/{uuid}:
    get:
      tags:
        - Player
      operationId: getPlayer
      description: This returns the Playerinformation or the occured error.
      parameters:
        - $ref: "#/components/parameters/uuid"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/playerResponse"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/generalError"
  /player/health/{uuid}:
    post:
      tags:
        - Player Health
      operationId: setPlayerHealth
      description: This sets the health of the given player.
      parameters:
        - $ref: "#/components/parameters/uuid"
        - $ref: "#/components/parameters/value"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/success"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/generalError"
  /player/food/{uuid}:
    post:
      tags:
        - Player Food
      operationId: setPlayerHealth
      description: This sets the Food Level of the given player.
      parameters:
        - $ref: "#/components/parameters/uuid"
        - $ref: "#/components/parameters/value"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/success"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/generalError"
  /player/saturation/{uuid}:
    post:
      tags:
        - Player Food
      operationId: setPlayerHealth
      description: This sets the Saturation of the given player.
      parameters:
        - $ref: "#/components/parameters/uuid"
        - $ref: "#/components/parameters/value"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/success"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/generalError"
components:
  parameters:
    uuid:
      name: uuid
      in: path
      required: true
      schema:
        type: string
        example: 069a79f4-44e9-4726-a5be-fca90e38aaf5
    name:
      name: playername
      in: path
      required: true
      schema:
        type: string
        example: Notch
    value:
      name: value
      in: query
      required: true
      schema:
        type: integer
        example: 20
  schemas:
    generalError:
      type: object
      required:
        - name
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          example: The given Player was not found.
    success:
      type: object
      required:
        - name
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Executed action successfully
    playerList:
      description: Array of Players
      type: object
      properties:
        players:
          type: array
          items:
            $ref: '#/components/schemas/player'
    playerResponse:
      type: object
      required:
        - uuid
      properties:
        status:
          type: string
          example: success
        player:
          type: object
          properties:
            name:
              type: string
              example: Notch
            uuid:
              type: string
              example: 069a79f4-44e9-4726-a5be-fca90e38aaf5
            ipaddress:
              type: string
              example: 192.168.178.32
            location:
              type: string
              example: todo
            worldname:
              type: string
              example: todo
            health:
              type: number
              format: double
              example: 20.0
            foodlevel:
              type: number
              format: float
              example: 15.0
            saturation:
              type: number
              format: float
              example: 18.0
            level:
              type: integer
              example: 3
            experience:
              type: integer
              example: 51
            gamemode:
              type: string
              example: SURVIVAL
    player:
      type: object
      properties:
        name:
          type: string
          example: Notch
        uuid:
          type: string
          example: 069a79f4-44e9-4726-a5be-fca90e38aaf5