openapi3-example.yaml

# OpenAPI 3.0 示例 - 包含所有校验规则场景
#
# 本文件故意包含各种校验问题，用于测试和演示校验分析功能
# 加载此文件后，系统会自动检测并给出修复建议
#
# 校验规则场景：
# - DFX-001: 路径包含 // (已包含)
# - DFX-002: 路径不以 / 开头 (已包含)
# - DFX-003: 必填参数缺少 @NotNull/@NotBlank (已包含)
# - DFX-004: String字段缺少长度校验 (已包含)
# - DFX-005: 邮箱字段缺少格式校验 (已包含)
# - DFX-006: 电话字段缺少正则校验 (已包含)
# - DFX-007: 数值字段缺少范围校验 (已包含)
# - DFX-008: List字段缺少大小校验 (已包含)
# - DFX-009: minLength > maxLength (已包含)
# - DFX-010: min > max (已包含)
# - DFX-011: page参数缺少范围校验 (已包含)
# - DFX-012: pageSize参数缺少范围校验 (已包含)
# - DFX-014: 路径参数缺少最小值校验 (已包含)
# - DFX-020: 注解位置一致性校验 (已包含)
# - WARN: 必填参数缺少 description (已包含)
# - INFO: 邮箱/电话/生日/预约字段优化建议 (已包含)

openapi: 3.0.0
info:
  title: 订单管理 API - 完整校验示例
  version: v1.0.0
  description: 包含所有校验规则场景的测试API
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: https://api.example.com/v1
    description: 生产环境

# ========== components/schemas - 用于测试字段级别变更 ==========
# 注意：这里的字段故意缺少校验规则，用于测试"字段变更"功能
components:
  schemas:
    # ========== 实体字段变更示例场景 ==========
    # 下面的模型故意展示"实体前后变化"的典型场景：
    # - 字段新增（added）：修复后新增字段
    # - 字段删除（deleted）：修复后删除字段
    # - 字段修改（modified）：修复后字段类型或校验规则变化

    # 场景A: UserModel 演示字段新增
    UserModel:
      type: object
      description: 用户模型 - 演示字段新增场景
      properties:
        userId:
          type: integer
          description: 用户ID
        username:
          type: string
          description: 用户名
          minLength: 2
          maxLength: 50
        email:
          type: string
          description: 邮箱
          format: email
        phone:
          type: string
          description: 手机号
          pattern: '^1[3-9]\d{9}$'
        # 注意：修复后会新增以下字段（age, status, avatarUrl, createdAt）
        # 这些字段在当前版本中故意不存在，用于测试"新增字段"场景

    # 场景B: LegacyUserModel 演示字段删除
    LegacyUserModel:
      type: object
      description: 旧版用户模型 - 演示字段删除场景
      properties:
        userId:
          type: integer
          description: 用户ID
        username:
          type: string
          description: 用户名
        oldPasswordField:
          type: string
          description: "旧密码字段(已废弃,修复后将被删除)"
        deprecatedFlag:
          type: boolean
          description: "已废弃标记(修复后将被删除)"
        legacyUserCode:
          type: string
          description: "旧版编码(修复后将被删除)"
        email:
          type: string
          description: 邮箱

    # 场景C: ProductModel 演示字段修改
    ProductModel:
      type: object
      description: 商品模型 - 演示字段修改场景
      properties:
        productId:
          type: integer
          description: 商品ID
        productName:
          type: string
          description: 商品名称
          minLength: 1
          maxLength: 100
        price:
          type: number
          format: double
          description: "价格(修复后将从number改为decimal并增加minimum)"
        quantity:
          type: integer
          description: "数量(修复后将增加范围校验minimum:0)"
        category:
          type: string
          description: "分类(修复后将增加枚举限制)"
        # 注意：以上字段故意缺少完整校验，修复后会变化

    # 场景D: OrderModel 演示综合变更(新增+删除+修改)
    OrderModel:
      type: object
      description: 订单模型 - 演示综合字段变更场景(故意缺少校验规则)
      properties:
        orderId:
          type: integer
          description: 订单ID
        orderNo:
          type: string
          description: 订单编号
        customerName:
          type: string
          description: 客户姓名
        contactEmail:
          type: string
          description: 联系邮箱
        contactPhone:
          type: string
          description: 联系电话
        # 删除字段:legacyOrderType(已废弃,修复后删除)
        legacyOrderType:
          type: string
          description: "旧版订单类型(修复后删除)"
        # 修改字段:totalAmount(修复后增加范围校验)
        totalAmount:
          type: number
          description: "订单金额(修复后将增加minimum:0)"
        # 新增字段:修复后会新增orderStatus,paymentMethod
        productList:
          type: array
          items:
            $ref: '#/components/schemas/OrderItemModel'
          description: 商品列表

    OrderItemModel:
      type: object
      description: 订单商品明细
      properties:
        productId:
          type: integer
          description: 商品ID
        productName:
          type: string
          description: 商品名称
        quantity:
          type: integer
          description: "数量(修复后将增加minimum:1)"
        unitPrice:
          type: number
          description: "单价(修复后将增加minimum:0)"

paths:
  # ========== 实体变更展示API - 使用 $ref 引用 components/schemas ==========
  /model/user:
    get:
      summary: 获取用户模型 - 字段新增场景
      operationId: getUserModel
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserModel'

  /model/legacy-user:
    get:
      summary: 获取旧版用户模型 - 字段删除场景
      operationId: getLegacyUserModel
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyUserModel'

  /model/product:
    get:
      summary: 获取商品模型 - 字段修改场景
      operationId: getProductModel
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductModel'

  /model/order:
    get:
      summary: 获取订单模型 - 综合变更场景
      operationId: getOrderModel
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderModel'

  /model/orders:
    post:
      summary: 创建订单 - 使用 OrderModel
      operationId: createOrderModel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderModel'
      responses:
        '200':
          description: 成功

  # ========== 正常API - 作为对比 ==========
  /orders:
    get:
      summary: 获取订单列表 - 完整示例
      description: 分页获取订单列表
      operationId: getOrderList
      parameters:
        - name: page
          in: query
          required: true
          description: 页码
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: pageSize
          in: query
          required: true
          description: 每页数量
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: keyword
          in: query
          description: 搜索关键词
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: orderBy
          in: query
          description: 排序字段
          schema:
            type: string
            minLength: 1
            maxLength: 50
      responses:
        '200':
          description: 成功

  # ========== DFX-001: 路径包含 // ==========
  //XXX/orders/detail:
    get:
      summary: 订单详情 - 路径问题
      operationId: getOrderDetail
      parameters:
        - name: orderId
          in: query
          required: true
      responses:
        '200':
          description: Success

  # ========== DFX-002: 路径不以 / 开头 ==========
  orders/export:
    get:
      summary: 导出订单 - 路径问题
      operationId: exportOrders
      responses:
        '200':
          description: Success

  # ========== DFX-003: 必填参数缺少 @NotNull ==========
  /api/orderInfo:
    get:
      summary: 获取订单信息 - 必填参数问题
      operationId: getOrderInfo
      parameters:
        - name: orderId
          in: query
          required: true
          description: 订单ID
          schema:
            type: integer
            # 缺少 minimum: 1
      responses:
        '200':
          description: 成功

  # ========== DFX-004: String字段缺少长度校验 ==========
  /api/search:
    get:
      summary: 搜索订单 - String长度校验问题
      operationId: searchOrders
      parameters:
        - name: keyword
          in: query
          description: 搜索关键词
          schema:
            type: string
            # 缺少 minLength/maxLength
      responses:
        '200':
          description: 成功

  # ========== DFX-005: 邮箱字段缺少格式校验 ==========
  /api/verifyEmail:
    post:
      summary: 验证邮箱 - 邮箱校验问题
      operationId: verifyEmail
      parameters:
        - name: email
          in: query
          required: true
          description: 邮箱地址
          schema:
            type: string
            format: email
            # 缺少其他校验
      responses:
        '200':
          description: 成功

  # ========== DFX-006: 电话字段缺少正则校验 ==========
  /api/sendNotify:
    post:
      summary: 发送通知 - 电话校验问题
      operationId: sendNotify
      parameters:
        - name: phone
          in: query
          required: true
          description: 手机号
          schema:
            type: string
            # 缺少 pattern
      responses:
        '200':
          description: 成功

  # ========== DFX-007: 数值字段缺少范围校验 ==========
  /api/price:
    get:
      summary: 获取价格 - 数值范围问题
      operationId: getPrice
      parameters:
        - name: price
          in: query
          description: 价格
          schema:
            type: number
            # 缺少 minimum/maximum
      responses:
        '200':
          description: 成功

  # ========== DFX-008: List字段缺少大小校验 ==========
  /api/products:
    post:
      summary: 设置商品 - List大小问题
      operationId: setProducts
      parameters:
        - name: productIds
          in: query
          description: 商品ID列表
          schema:
            type: array
            items:
              type: integer
            # 缺少 minItems/maxItems
      responses:
        '200':
          description: 成功

  # ========== DFX-011: page参数缺少范围校验 ==========
  /api/list:
    get:
      summary: 列表查询 - 分页问题
      operationId: listItems
      parameters:
        - name: page
          in: query
          description: 页码
          schema:
            type: integer
            # 缺少 minimum: 1, maximum: 2147483647
        - name: pageNum
          in: query
          description: 页码2
          schema:
            type: integer
            # 缺少 minimum: 1, maximum: 2147483647
      responses:
        '200':
          description: 成功

  # ========== DFX-012: pageSize参数缺少范围校验 ==========
  /api/list2:
    get:
      summary: 列表查询2 - 分页大小问题
      operationId: listItems2
      parameters:
        - name: limit
          in: query
          description: 限制数量
          schema:
            type: integer
            # 缺少 minimum: 1, maximum: 100
        - name: size
          in: query
          description: 大小
          schema:
            type: integer
            # 缺少 minimum: 1, maximum: 100
      responses:
        '200':
          description: 成功

  # ========== DFX-014: 路径参数缺少最小值校验 ==========
  /orders/{orderId}:
    get:
      summary: 根据ID获取订单 - 路径参数数值问题
      operationId: getOrderById
      parameters:
        - name: orderId
          in: path
          required: true
          description: 订单ID
          schema:
            type: integer
            # 缺少 minimum: 1
      responses:
        '200':
          description: 成功

  /orders/{orderNo}:
    get:
      summary: 根据编号获取订单 - 路径参数字符串问题
      operationId: getOrderByNo
      parameters:
        - name: orderNo
          in: path
          required: true
          description: 订单编号
          schema:
            type: string
            # 缺少 minLength: 1
      responses:
        '200':
          description: 成功

  # ========== 完整示例: 包含header和cookie参数 ==========
  /orders/{orderId}/detail:
    get:
      summary: 获取订单详情 - 完整参数示例
      operationId: getOrderDetailFull
      parameters:
        - name: orderId
          in: path
          required: true
          description: 订单ID
          schema:
            type: integer
            minimum: 1
        - name: X-Token
          in: header
          required: true
          description: 认证令牌
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: SESSION_ID
          in: cookie
          description: 会话ID
          schema:
            type: string
            minLength: 1
            maxLength: 64
      responses:
        '200':
          description: 成功

  # ========== 创建订单 - 完整请求体示例 ==========
  /orders/create:
    post:
      summary: 创建订单 - RequestBody示例
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customerId
                - items
                - contactEmail
                - contactPhone
              properties:
                customerId:
                  type: integer
                  minimum: 1
                  description: 客户ID
                contactEmail:
                  type: string
                  format: email
                  description: 联系邮箱
                contactPhone:
                  type: string
                  pattern: '^1[3-9]\d{9}$'
                  description: 联系电话
                remark:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: 备注
                discount:
                  type: number
                  minimum: 0
                  maximum: 100
                  description: 折扣
                items:
                  type: array
                  minItems: 1
                  maxItems: 100
                  description: 订单商品
                  items:
                    type: object
                    properties:
                      productId:
                        type: integer
                        minimum: 1
                        description: 商品ID
                      quantity:
                        type: integer
                        minimum: 1
                        description: 数量
                      unitPrice:
                        type: number
                        minimum: 0
                        description: 单价
      responses:
        '201':
          description: 创建成功

  # ========== 使用 components/schemas 的示例 - 测试字段变更 ==========
  # 此 API 使用 $ref 引用 components/schemas 中的模型
  # 用于测试"字段变更"功能的检测
  /model/order:
    get:
      summary: 获取订单模型信息
      operationId: getOrderModel
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderModel'

  /model/orders:
    post:
      summary: 创建订单模型
      operationId: createOrderModel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderModel'
      responses:
        '200':
          description: 成功

  # ========== 自定义注解场景 - x-java-class-annotations ==========
  # 场景1: 类级别注解（path级别）
  /admin/users:
    x-java-class-annotations:
      - "@Secured"
      - "@AuditLog(action='USER_QUERY')"
    get:
      summary: 获取用户列表 - 带类注解
      operationId: getAdminUsers
      x-java-method-annotations:
        - "@Permission('admin:user:read')"
        - "@RateLimiter(maxRequests=100)"
      responses:
        '200':
          description: 成功

  # 场景2: 方法级别注解（operation级别）
  /admin/users/{id}:
    get:
      summary: 获取用户详情 - 仅有方法注解
      operationId: getAdminUserById
      x-java-method-annotations:
        - "@Permission('admin:user:read')"
        - "@Cacheable(key='#id')"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: 成功

  # 场景3: 同一路径下多个方法，类注解一致（正常场景）
  /secure:
    x-java-class-annotations:
      - "@Secured"
      - "@RequireRole('ADMIN')"
    get:
      summary: 获取安全配置 - GET
      operationId: getSecureConfig
      x-java-method-annotations:
        - "@AuditLog(action='SECURE_GET')"
      responses:
        '200':
          description: 成功
    post:
      summary: 更新安全配置 - POST
      operationId: updateSecureConfig
      x-java-method-annotations:
        - "@AuditLog(action='SECURE_UPDATE')"
        - "@Transactional"
      responses:
        '200':
          description: 成功

  # 场景4: 同一路径下类注解不一致（异常场景 - DFX-020）
  /inconsistent:
    x-java-class-annotations:
      - "@Secured"
    get:
      summary: 获取资源 - GET
      operationId: getInconsistent
      x-java-class-annotations:
        - "@DifferentAnnotation"  # 异常：与path级别注解不一致
      responses:
        '200':
          description: 成功
    post:
      summary: 创建资源 - POST
      operationId: createInconsistent
      # 异常：POST方法没有类注解，但GET有
      responses:
        '201':
          description: 创建成功

  # ========== DFX-009: minLength > maxLength 错误 ==========
  /api/invalid-length:
    get:
      summary: 搜索 - 长度范围错误
      operationId: searchInvalidLength
      parameters:
        - name: keyword
          in: query
          description: 搜索关键词
          schema:
            type: string
            minLength: 100
            maxLength: 10
      responses:
        '200':
          description: 成功

  # ========== DFX-010: min > max 错误 ==========
  /api/invalid-range:
    get:
      summary: 查询 - 数值范围错误
      operationId: queryInvalidRange
      parameters:
        - name: age
          in: query
          description: 年龄
          schema:
            type: integer
            minimum: 100
            maximum: 10
      responses:
        '200':
          description: 成功

  # ========== WARN: 必填参数缺少 description ==========
  /api/missing-description:
    get:
      summary: 查询 - 必填参数缺少描述
      operationId: queryMissingDesc
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功

  # ========== INFO: 邮箱字段建议添加 @Email ==========
  /api/suggest-email:
    post:
      summary: 注册 - 邮箱字段建议
      operationId: registerUser
      parameters:
        - name: email
          in: query
          description: 邮箱地址
          schema:
            type: string
            # 缺少 format: email，但字段名包含 email
      responses:
        '200':
          description: 成功

  # ========== INFO: 电话字段建议添加正则 ==========
  /api/suggest-phone:
    post:
      summary: 绑定手机号 - 电话字段建议
      operationId: bindPhone
      parameters:
        - name: mobile
          in: query
          description: 手机号
          schema:
            type: string
            # 缺少 pattern，但字段名包含 mobile
      responses:
        '200':
          description: 成功

  # ========== INFO: 生日字段建议添加 @Past ==========
  /api/suggest-birthday:
    post:
      summary: 设置生日 - 生日字段建议
      operationId: setBirthday
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                birthday:
                  type: string
                  format: date
                  description: 生日日期
                  # 字段名包含 birthday，但缺少 past: true
                dob:
                  type: string
                  format: date
                  description: 出生日期
      responses:
        '200':
          description: 成功

  # ========== INFO: 预约字段建议添加 @Future ==========
  /api/suggest-appointment:
    post:
      summary: 预约 - 预约字段建议
      operationId: createAppointment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scheduleTime:
                  type: string
                  format: date-time
                  description: 预约时间
                appointmentDate:
                  type: string
                  format: date
                  description: 预约日期
      responses:
        '200':
          description: 成功