openapi-parser

OpenAPI 解析器技能

参考文件

• references/schema-patterns.md — 如何解读并枚举每种复杂模式 （anyOf / oneOf / allOf / discriminator / $ref / enum / pattern / nullable / optional）， 并提供来自 snyk、digitalocean、posthog 和 front/core 规范的真实示例
• references/drift-mapping.md — 如何将枚举出的 schema 变体映射到 Drift YAML， 包括数据集、表达式、有状态情形的生命周期钩子，以及每种模式类型对应的预期 响应匹配器

工作流

OpenAPI 版本： 此技能适用于 OpenAPI 3.x。Swagger 2.0 规范使用相同的结构模式（$ref、allOf、oneOf），但封装语法不同——你可能需要手动调整字段名称。 如果使用 konfig-sdks/openapi-examples 集合，请参阅 references/example-repos.md 了解导航命令。

1. 定位端点

仅提取所需内容：

# Find the line number of the endpoint (macOS/Linux/Git Bash/WSL)
grep -n "^  /path/to/endpoint" spec.yaml

# Read just that block (adjust line range as needed)
# Then follow each $ref to components/schemas
grep -n "SchemaName:" spec.yaml

# PowerShell equivalents (Windows)
Select-String -Path spec.yaml -Pattern "^  /path/to/endpoint" | Select-Object LineNumber, Line
Select-String -Path spec.yaml -Pattern "SchemaName:" | Select-Object LineNumber, Line

提取：路径／查询／标头参数、请求体 schema，以及每个响应状态码的 schema。

2. 递归解析 $refs

1. 在规范中搜索 Foo:，找到其定义块
2. 如果 Foo 本身包含 refs，也要解析这些 refs
3. 遇到基本类型（string、integer、boolean、array、object）时停止

allOf: [$ref: Base, properties: {...}] 表示继承——将 Base 字段与本地 属性合并，以获取完整 schema。所有模式请参阅 references/schema-patterns.md。

3. 枚举可行组合

对于每个响应状态码，枚举结构上不同的 schema 变体。目标是在最大化 schema 覆盖率的同时，将测试数量降至最低——避免可选字段排列组合导致的爆炸。

模式	要生成的测试
oneOf / anyOf，包含 N 个分支	N 个测试——每个分支一个
discriminator，包含 N 个映射值	N 个测试——每个 discriminator 值一个
allOf（组合／继承）	1 个测试——将所有 schema 合并到一个载荷中
enum	1 个测试即可覆盖；只有当该值会影响行为时，才添加边界变体
可选字段组	2 个测试：一个包含所有可选字段，一个不包含
nullable 字段	由正常路径覆盖；只有当 null 会改变行为时，才添加 null 变体
pattern（正则表达式）	1 个符合模式的有效示例；1 个用于负向测试的无效示例

4. 生成 Drift 测试用例

为每种组合生成一个 Drift 操作块。完整模式请参阅 references/drift-mapping.md。 关键约定：

• 将操作命名为 {operationId}_{variant}——例如 getImage_byId、getImage_bySlug
• 对于带 discriminator 的联合类型，在请求体中显式设置 discriminator 属性
• 对于 anyOf 路径参数，每种类型变体编写一个测试
• 使用 dataset 存放测试数据；仅对静态且无变体的值使用内联 parameters（例如固定的枚举查询参数，如 type: user）
• 对于 401 测试，使用 exclude: [auth] 移除全局身份验证，并显式传入无效的 bearer token
• 对于任何有意发送无效请求体的操作，添加 ignore: { schema: true }
• 为每个测试添加标签，标明其覆盖的 schema 分支
• 从 expected 中省略 body，即可让 Drift 自动根据 OpenAPI schema 验证响应；仅当要断言特定字段值时，才添加显式的 body 匹配器（例如确认返回的 discriminator 属性正确）

5. 输出格式

始终提供：

1. 分析 — 状态码数量、多态 Schema 的类型、将生成多少个测试及原因
2. Drift 操作 YAML — 完整的 operations: 块，可直接粘贴
3. 数据集 YAML（如有需要）— 所引用测试数据的 datasets: 块
4. 缺漏 — 有意排除的 Schema 组合及原因

示例

给定 GET /v2/images/{image_id}，其中 image_id: anyOf: [integer, string]：

operations:
  getImage_byId:
    target: source-oas:getImage
    tags: [images, param-integer]
    parameters:
      path:
        image_id: ${image-data:images.existing.id}
    expected:
      response:
        statusCode: 200

  getImage_bySlug:
    target: source-oas:getImage
    tags: [images, param-string]
    parameters:
      path:
        image_id: ${image-data:images.existing.slug}
    expected:
      response:
        statusCode: 200

  getImage_notFound:
    target: source-oas:getImage
    parameters:
      path:
        image_id: ${image-data:notIn(images.*.id)}
    expected:
      response:
        statusCode: 404