getUserNames:
  get:
    tags:
      - history
    summary: Get user names
    description: Get all user names with punishment history of the specified type
    operationId: getUserNames
    parameters:
      - $ref: '#/components/parameters/UserType'
      - $ref: '#/components/parameters/HistoryType'
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                description: A list of users
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
getHistoryForUsers:
  get:
    tags:
      - history
    summary: Get history for users
    description: >
      Get all users with punishment history of the specified type,
      where the user name starts with the search query, 100 records at a time
    operationId: getHistoryForUsers
    parameters:
      - $ref: '#/components/parameters/UserType'
      - $ref: '#/components/parameters/HistoryType'
      - $ref: '#/components/parameters/User'
      - $ref: '#/components/parameters/Page'
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PunishmentHistoryList'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
getHistoryForAll:
  get:
    tags:
      - history
    summary: Get history for users
    description: >
      Get all users with punishment history of the specified type,
      where the user name starts with the search query, 100 records at a time
    operationId: getHistoryForAll
    parameters:
      - $ref: '#/components/parameters/UserType'
      - $ref: '#/components/parameters/HistoryType'
      - $ref: '#/components/parameters/Page'
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PunishmentHistoryList'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
getHistoryForUuid:
  get:
    tags:
      - history
    summary: Get user
    description: >
      Get all users with punishment history of the specified type,
      where the user uuid matches, 100 records at a time
    operationId: getHistoryForUuid
    parameters:
      - $ref: '#/components/parameters/UserType'
      - $ref: '#/components/parameters/HistoryType'
      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
      - $ref: '#/components/parameters/Page'
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PunishmentHistoryList'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
getTotalPunishments:
  get:
    tags:
      - history
    summary: Get total history count per type
    description: Retrieves the total count of punishments for each type available (ban, mute, kick, warn, or all).
    operationId: getTotalPunishments
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HistoryCount'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
getTotalResultsForUserSearch:
  get:
    tags:
      - history
    summary: Gets total results for search query
    description: Retrieves the total count of punishments for the search query
    operationId: getTotalResultsForUserSearch
    parameters:
      - $ref: '#/components/parameters/UserType'
      - $ref: '#/components/parameters/HistoryType'
      - $ref: '#/components/parameters/User'
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchResults'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
getTotalResultsForUuidSearch:
  get:
    tags:
      - history
    summary: Gets total results for search query
    description: Retrieves the total count of punishments for the search query
    operationId: getTotalResultsForUuidSearch
    parameters:
      - $ref: '#/components/parameters/UserType'
      - $ref: '#/components/parameters/HistoryType'
      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchResults'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
getHistoryById:
  get:
    tags:
      - history
    summary: Gets history for specified id
    description: Retrieves a specific history record
    operationId: getHistoryById
    parameters:
      - $ref: '#/components/parameters/HistoryType'
      - $ref: '#/components/parameters/Id'
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PunishmentHistory'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../generic/errors.yml#/components/schemas/ApiError'
getAllHistoryForUUID:
  get:
    tags:
      - history
    summary: Gets all history for specified UUID
    description: Retrieves all history for specified UUID
    operationId: getAllHistoryForUUID
    parameters:
      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PunishmentHistoryList'
components:
  parameters:
    HistoryType:
      name: type
      in: path
      required: true
      schema:
        type: string
        enum: [ all, ban, mute, kick, warn ]
        description: The type of history to retrieve
    User:
      name: user
      in: path
      required: true
      schema:
        type: string
        description: The (partial) username to search for
    UserType:
      name: userType
      in: path
      required: true
      schema:
        type: string
        enum: [ player, staff ]
        description: Indicates if this is a staff history or a player history look up
    Page:
      name: page
      in: path
      required: true
      schema:
        type: integer
        description: The page that should be retrieved
    Id:
      name: id
      in: path
      required: true
      schema:
        type: integer
        description: The id of the punishment that should be retrieved
  schemas:
    SearchResults:
      type: integer
      description: A number representing the total count of results for the search query
    PunishmentHistoryList:
      type: array
      items:
        $ref: '#/components/schemas/PunishmentHistory'
    PunishmentHistory:
      type: object
      required:
        - username
        - uuid
        - reason
        - type
        - punishmentTime
        - expiryTime
        - punishedBy
        - punishedByUuid
        - id
      properties:
        username:
          type: string
          description: The username of the user
        uuid:
          type: string
          description: The UUID of the user
        reason:
          type: string
          description: The reason for the punishment
        type:
          type: string
          description: The type of punishment
          enum: [ ban, mute, kick, warn ]
        punishmentTime:
          type: integer
          format: int64
          description: The time when the punishment was given
        expiryTime:
          type: integer
          format: int64
          description: The time when the punishment expires
        punishedBy:
          type: string
          description: The username of the punishment issuer
        punishedByUuid:
          type: string
          description: The UUID of the punishment issuer
        removedBy:
          type: string
          description: The name of the staff member who removed the punishment
        removedReason:
          type: string
          description: The reason why the punishment was removed
        id:
          type: integer
          description: Id of the punishment
    Player:
      type: object
      properties:
        name:
          type: string
          description: The name of the player
          example: a_name
        uuid:
          type: string
          example: 0c35e520-927e-4c6a-87ad-ff0739c22e9d
          description: The uuid of the team player
      required:
        - name
        - uuid
    HistoryCount:
      type: object
      required:
        - bans
        - mutes
        - warnings
        - kicks
      properties:
        bans:
          type: integer
          description: The total amounts of bans
          example: 10528
        mutes:
          type: integer
          description: The total amounts of mutes
          example: 2350
        warnings:
          type: integer
          description: The total amounts of warnings
          example: 3881
        kicks:
          type: integer
          description: The total amounts of kicks
          example: 1769