users:
  get:
    tags:
      - users
    summary: 获取用户列表
    operationId: listUsers
    parameters:
      - $ref: '../components/parameters.yaml#/Page'
      - $ref: '../components/parameters.yaml#/PerPage'
      - $ref: '../components/parameters.yaml#/Sort'
      - name: role
        in: query
        schema:
          type: string
          enum:
            - admin
            - editor
        description: 按角色筛选
      - name: status
        in: query
        schema:
          type: string
          enum:
            - active
            - inactive
        description: 按状态筛选
      - name: email
        in: query
        schema:
          type: string
        description: 按邮箱搜索
    responses:
      '200':
        description: 成功获取用户列表
        content:
          application/json:
            schema:
              allOf:
                - $ref: '../components/schemas.yaml#/Response'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '../components/schemas.yaml#/User'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
  post:
    tags:
      - users
    summary: 创建新用户
    operationId: createUser
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - email
              - password
              - role
            properties:
              email:
                type: string
                format: email
              password:
                type: string
                minLength: 8
              role:
                type: string
                enum:
                  - admin
                  - editor
    responses:
      '201':
        description: 用户创建成功
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '../components/schemas.yaml#/User'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '422':
        $ref: '../components/responses.yaml#/ValidationError'

user_id:
  parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
  get:
    tags:
      - users
    summary: 获取用户详情
    operationId: getUser
    responses:
      '200':
        description: 成功获取用户详情
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '../components/schemas.yaml#/User'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
  put:
    tags:
      - users
    summary: 更新用户信息
    operationId: updateUser
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              email:
                type: string
                format: email
              password:
                type: string
                minLength: 8
              role:
                type: string
                enum:
                  - admin
                  - editor
              status:
                type: string
                enum:
                  - active
                  - inactive
    responses:
      '200':
        description: 用户更新成功
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '../components/schemas.yaml#/User'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '422':
        $ref: '../components/responses.yaml#/ValidationError'
  delete:
    tags:
      - users
    summary: 删除用户
    operationId: deleteUser
    responses:
      '204':
        description: 用户删除成功
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '422':
        description: 验证错误，例如用户还有关联的内容
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/Error'

user_me:
  get:
    tags:
      - users
    summary: 获取当前用户信息
    operationId: getCurrentUser
    responses:
      '200':
        description: 成功获取当前用户信息
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '../components/schemas.yaml#/User'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
  put:
    tags:
      - users
    summary: 更新当前用户信息
    operationId: updateCurrentUser
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              username:
                type: string
                minLength: 3
                maxLength: 32
              display_name:
                type: string
                maxLength: 64
              email:
                type: string
                format: email
              current_password:
                type: string
                description: 当修改密码时必填
              new_password:
                type: string
                minLength: 8
                description: 新密码，如果要修改密码则必填
    responses:
      '200':
        description: 用户信息更新成功
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '../components/schemas.yaml#/User'
      '401':
        $ref: '../components/responses.yaml#/Unauthorized'
      '422':
        $ref: '../components/responses.yaml#/ValidationError'