openapi: 3.0.0
info:
  title: 认证授权模块API
  version: 1.0.0
  description: 负责用户认证、授权和Token管理

paths:
  /api/v1/auth/login:
    post:
      summary: 用户登录
      tags: [认证]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: 用户名或邮箱
                password:
                  type: string
                  description: 密码
              required:
                - username
                - password
      responses:
        200:
          description: 登录成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        400:
          description: 请求参数错误
        401:
          description: 用户名或密码错误
        403:
          description: 账号已被禁用

  /api/v1/auth/register:
    post:
      summary: 用户注册
      tags: [认证]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegister'
      responses:
        201:
          description: 注册成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        400:
          description: 参数验证失败
        409:
          description: 用户名或邮箱已存在

  /api/v1/auth/logout:
    post:
      summary: 用户登出
      tags: [认证]
      security:
        - bearerAuth: []
      responses:
        200:
          description: 登出成功
        401:
          description: 未授权

  /api/v1/auth/refresh:
    post:
      summary: 刷新Token
      tags: [认证]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
              required:
                - refresh_token
      responses:
        200:
          description: 刷新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        401:
          description: 刷新Token无效

  /api/v1/auth/reset-password:
    post:
      summary: 重置密码请求
      tags: [认证]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
              required:
                - email
      responses:
        200:
          description: 重置邮件已发送
        404:
          description: 邮箱不存在

components:
  schemas:
    UserRegister:
      type: object
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 20
          pattern: '^[a-zA-Z0-9_-]+$'
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
        confirm_password:
          type: string
      required:
        - username
        - email
        - password
        - confirm_password

    TokenResponse:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: success
        data:
          type: object
          properties:
            access_token:
              type: string
            refresh_token:
              type: string
            token_type:
              type: string
              example: bearer
            expires_in:
              type: integer
              example: 1800
            user:
              type: object
              properties:
                id:
                  type: integer
                username:
                  type: string
                email:
                  type: string
                role:
                  type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
