ars-backend/docs/user/user-openapi.yaml

openapi: 3.0.3
info:
  title: ars-backend API (JWT)
  version: 1.0.0
  description: |
    ars-backend 无状态 API，认证方式为 JWT Bearer。自然语言：中文。
servers:
  - url: http://localhost:8000/api
    description: 本地开发（FrankenPHP Octane，Docker）
tags:
  - name: System
    description: 系统与健康检查
  - name: Auth
    description: 认证相关接口
  - name: Users
    description: 用户管理接口（需 JWT）
paths:
  /health:
    get:
      tags: [System]
      summary: 健康检查
      responses:
        "200":
          description: 服务可用
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /login:
    post:
      tags: [Auth]
      summary: 用户登录
      description: 使用邮箱和密码换取 JWT，停用用户返回 403。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        "200":
          description: 登录成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        "401":
          description: 凭证无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "403":
          description: 用户已停用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /me:
    get:
      tags: [Auth]
      summary: 获取当前用户
      security:
        - bearerAuth: []
      responses:
        "200":
          description: 当前登录用户
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: 未授权或 token 失效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users:
    get:
      tags: [Users]
      summary: 用户列表
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: 页码（默认 1）
        - in: query
          name: per_page
          schema:
            type: integer
            default: 15
            maximum: 100
          description: 每页数量（1-100，默认 15）
      responses:
        "200":
          description: 分页用户列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPagination'
        "401":
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags: [Users]
      summary: 创建用户
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        "201":
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "422":
          description: 参数校验失败
  /users/{id}:
    put:
      tags: [Users]
      summary: 更新用户
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        "200":
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "422":
          description: 参数校验失败
  /users/{id}/deactivate:
    post:
      tags: [Users]
      summary: 停用用户
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 已停用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{id}/activate:
    post:
      tags: [Users]
      summary: 启用用户
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 已启用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: root
        email:
          type: string
          format: email
          example: root@example.com
        is_active:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
          example: 2025-12-14T05:37:47.000000Z
        updated_at:
          type: string
          format: date-time
          example: 2025-12-14T05:37:47.000000Z
    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
          example: root@example.com
        password:
          type: string
          format: password
          example: Root@123456
    CreateUserRequest:
      type: object
      required: [name, email, password]
      properties:
        name:
          type: string
          example: Alice
        email:
          type: string
          format: email
          example: alice@example.com
        password:
          type: string
          format: password
          example: Password123
    UpdateUserRequest:
      type: object
      properties:
        name:
          type: string
          example: Alice Updated
        email:
          type: string
          format: email
          example: alice.updated@example.com
        password:
          type: string
          format: password
          example: NewPassword123
    AuthResponse:
      type: object
      properties:
        token:
          type: string
          example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
        token_type:
          type: string
          example: bearer
        expires_in:
          type: integer
          example: 3600
        user:
          $ref: '#/components/schemas/User'
    Error:
      type: object
      properties:
        message:
          type: string
          example: 凭证无效
    UserPagination:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        links:
          $ref: '#/components/schemas/PaginationLinks'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaginationLinks:
      type: object
      properties:
        first:
          type: string
          example: http://localhost:8000/api/users?page=1
        last:
          type: string
          example: http://localhost:8000/api/users?page=1
        prev:
          type: string
          nullable: true
        next:
          type: string
          nullable: true
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        from:
          type: integer
          example: 1
        last_page:
          type: integer
          example: 1
        path:
          type: string
          example: http://localhost:8000/api/users
        per_page:
          type: integer
          example: 15
        to:
          type: integer
          example: 3
        total:
          type: integer
          example: 3