openapi: 3.0.2

paths:
  /admin/users:
    post:
      summary: Create a new user
      tags:
        - Users

      security:
        - bearerAuth: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterUser'

      responses:
        201:
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User created successfully
                  user:
                    $ref: '#/components/schemas/UserResponse'

        400:
          $ref: '#/components/responses/BadRequest'

        401:
          $ref: '#/components/responses/Unauthorized'

        500:
          $ref: '#/components/responses/InternalServerError'

    get:
      summary: Retrieve a list of all users
      tags:
        - Users

      security:
        - bearerAuth: []

      responses:
        200:
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserResponse'

        401:
          $ref: '#/components/responses/Unauthorized'

        500:
          $ref: '#/components/responses/InternalServerError'

  /admin/users/{id}:
    get:
      summary: Retrieve a user by ID
      tags:
        - Users

      security:
        - bearerAuth: []

      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the user to retrieve
          schema:
            type: string
            example: 018f22d5-4b3a-7c21-b93f-9a5aefc1b847

      responses:
        200:
          description: A single user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'

        400:
          $ref: '#/components/responses/BadRequest'

        401:
          $ref: '#/components/responses/Unauthorized'

        404:
          $ref: '#/components/responses/NotFoundError'

        500:
          $ref: '#/components/responses/InternalServerError'

    put:
      summary: Update a user's information by ID
      tags:
        - Users

      security:
        - bearerAuth: []

      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the user to update
          schema:
            type: string
            example: 018f22d5-4b3a-7c21-b93f-9a5aefc1b847

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'

      responses:
        200:
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User updated successfully
                  user:
                    $ref: '#/components/schemas/UserResponse'

        400:
          $ref: '#/components/responses/BadRequest'

        401:
          $ref: '#/components/responses/Unauthorized'

        404:
          $ref: '#/components/responses/NotFoundError'

        500:
          $ref: '#/components/responses/InternalServerError'

    delete:
      summary: Delete a user by ID
      tags:
        - Users

      security:
        - bearerAuth: []

      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the user to delete
          schema:
            type: string
            example: 018f22d5-4b3a-7c21-b93f-9a5aefc1b847

      responses:
        200:
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User deleted successfully
                  user:
                    $ref: '#/components/schemas/UserResponse'

        400:
          $ref: '#/components/responses/BadRequest'

        401:
          $ref: '#/components/responses/Unauthorized'

        404:
          $ref: '#/components/responses/NotFoundError'

        500:
          $ref: '#/components/responses/InternalServerError'

  /admin/users/{id}/roles:
    get:
      summary: Retrieve all roles for a user by ID
      tags:
        - Users

      security:
        - bearerAuth: []

      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the user
          schema:
            type: string
            example: 018f22d5-4b3a-7c21-b93f-9a5aefc1b847

      responses:
        200:
          description: A list of roles for the user
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RolesResponse'

        400:
          $ref: '#/components/responses/BadRequest'

        401:
          $ref: '#/components/responses/Unauthorized'

        404:
          $ref: '#/components/responses/NotFoundError'

        500:
          $ref: '#/components/responses/InternalServerError'

    post:
      summary: Assign roles to a user by ID
      tags:
        - Users

      security:
        - bearerAuth: []

      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the user to assign roles to
          schema:
            type: string
            example: 018f22d5-4b3a-7c21-b93f-9a5aefc1b847

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rolesIds
              properties:
                rolesIds:
                  type: array
                  description: A list of role IDs to assign
                  items:
                    type: string
                    example: 018f22d5-4b3a-7c21-b93f-9a5aefc1b847

      responses:
        200:
          description: Roles assigned to user successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Roles assigned to user successfully
                  user:
                    $ref: '#/components/schemas/UserResponse'

        400:
          $ref: '#/components/responses/BadRequest'

        401:
          $ref: '#/components/responses/Unauthorized'

        404:
          $ref: '#/components/responses/NotFoundError'

        500:
          $ref: '#/components/responses/InternalServerError'

    delete:
      summary: Remove roles from a user by ID
      tags:
        - Users

      security:
        - bearerAuth: []

      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the user to remove roles from
          schema:
            type: string
            example: 018f22d5-4b3a-7c21-b93f-9a5aefc1b847

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rolesIds
              properties:
                rolesIds:
                  type: array
                  description: A list of role IDs to remove
                  items:
                    type: string
                  example:
                    - "018f22d5-4b3a-7c21-b93f-9a5aefc1b847"

      responses:
        200:
          description: Roles removed from user successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User roles removed successfully
                  user:
                    $ref: '#/components/schemas/UserResponse'

        400:
          $ref: '#/components/responses/BadRequest'

        401:
          $ref: '#/components/responses/Unauthorized'

        404:
          $ref: '#/components/responses/NotFoundError'

        500:
          $ref: '#/components/responses/InternalServerError'
