get:
  summary: Get user info
  parameters:
  - in: path
    name: user_id
    required: true
    schema:
      type: string
  - in: query
    name: fields
    schema:
      type: string
      default: all
  responses:
    '200':
      description: User info
      content:
        application/json:
          schema:
            $ref: '../schemas/User.yaml'
    '404':
      description: User not found
    '400':
      description: Request params are not correct
    '500':
      description: Unknown server error

patch:
  summary: Partially update a user account
  description: |
    Update selected user profile fields (excluding password). 
    Password updates must be done via the dedicated auth-service (`/auth/`).
    Fields not provided in the request body remain unchanged.
  operationId: updateUser
  parameters:
    - name: user_id
      in: path
      required: true
      schema:
        type: integer
        format: int64
      description: User ID (primary key)
      example: 123
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            avatar_id:
              type: integer
              format: int64
              nullable: true
              description: ID of the user avatar (references `images.id`); set to `null` to remove avatar
              example: 42
            mail:
              type: string
              format: email
              pattern: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\\.[a-zA-Z0-9_-]+$'
              description: User email (must be unique and valid)
              example: john.doe.updated@example.com
            nickname:
              type: string
              pattern: '^[a-zA-Z0-9_-]{3,16}$'
              description: Username (alphanumeric + `_` or `-`, 3–16 chars)
              maxLength: 16
              minLength: 3
              example: john_doe_43
            disp_name:
              type: string
              description: Display name
              maxLength: 32
              example: John Smith
            user_desc:
              type: string
              description: User description / bio
              maxLength: 512
              example: Just a curious developer.
          additionalProperties: false
          description: Only provided fields are updated. Omitted fields remain unchanged.
  responses:
    '200':
      description: User updated successfully. Returns updated user representation (excluding sensitive fields).
      content:
        application/json:
          schema:
            $ref: '../schemas/User.yaml'
    '400':
      description: Invalid input (e.g., validation failed, nickname/email conflict, malformed JSON)
    '401':
      description: Unauthorized — missing or invalid authentication token
    '403':
      description: Forbidden — user is not allowed to modify this resource (e.g., not own profile & no admin rights)
    '404':
      description: User not found
    '409':
      description: Conflict — e.g., requested `nickname` or `mail` already taken by another user
    '422':
      description: Unprocessable Entity — semantic errors not caught by schema (e.g., invalid `avatar_id`)
    '500':
      description: Unknown server error