openapi-parser

name	openapi-parser
description	Parses complex OpenAPI specs and generates Drift test cases from them. Use whenever the user wants to generate, write, or scaffold Drift tests from an OpenAPI spec — especially when the spec contains complex schemas: anyOf/oneOf/allOf, discriminators, polymorphism, inheritance, $ref chains, regex patterns, enums, or optional fields. Use when the user asks to "create tests for an endpoint", "cover all response variants", "generate test cases from the spec", or says anything like "each viable combination of responses". Use when the user is trying to understand what values are valid for a complex schema field, or when they paste a spec path and ask what tests to write.
argument-hint	[path/to/openapi-spec.yaml]
metadata	{"context":"fork","agent":"general-purpose"}

OpenAPI Parser Skill

Reference files

• references/schema-patterns.md — how to interpret and enumerate every complex pattern (anyOf / oneOf / allOf / discriminator / $ref / enum / pattern / nullable / optional), with real examples from snyk, digitalocean, posthog, and front/core specs
• references/drift-mapping.md — how to map enumerated schema variants to Drift YAML, including datasets, expressions, lifecycle hooks for stateful cases, and expected response matchers for each pattern type

Workflow

OpenAPI version: This skill targets OpenAPI 3.x. Swagger 2.0 specs use the same structural patterns ($ref, allOf, oneOf) but different envelope syntax — you may need to adapt field names manually. If working from the konfig-sdks/openapi-examples collection, see references/example-repos.md for navigation commands.

1. Locate the endpoint

Extract only what's needed:

# 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

Extract: path/query/header parameters, request body schema, and each response status code's schema.

2. Resolve $refs recursively

1. Grep for Foo: in the spec to find its definition block
2. If Foo itself contains refs, resolve those too
3. Stop at primitive types (string, integer, boolean, array, object)

allOf: [$ref: Base, properties: {...}] is inheritance — merge Base fields with local properties to get the full schema. See references/schema-patterns.md for all patterns.

3. Enumerate viable combinations

For each response status code, enumerate structurally distinct schema variants. Aim for minimum tests that maximise schema coverage — not a combinatorial explosion of optional field permutations.

Pattern	Tests to generate
oneOf / anyOf with N branches	N tests — one per branch
discriminator with N mapping values	N tests — one per discriminator value
allOf (composition / inheritance)	1 test — merge all schemas into one payload
enum	1 test covers it; add boundary variants only if the value drives behaviour
Optional field cluster	2 tests: one with all optional fields, one without
nullable field	Covered by happy path; add null variant only if it changes behaviour
pattern (regex)	1 valid example matching the pattern; 1 invalid for negative testing

4. Generate Drift test cases

For each combination produce a Drift operation block. See references/drift-mapping.md for full patterns. Key conventions:

• Name operations as {operationId}_{variant} — e.g. getImage_byId, getImage_bySlug
• For discriminated unions, set the discriminator property explicitly in the request body
• For anyOf path parameters, write one test per type variant
• Use dataset for test data; use inline parameters only for static, non-variant values (e.g. a fixed enum query param like type: user)
• For 401 tests, strip global auth with exclude: [auth] and pass an invalid bearer token explicitly
• Add ignore: { schema: true } to any operation that sends an intentionally invalid request body
• Tag each test to indicate which schema branch it covers
• Omitting body from expected lets Drift validate the response against the OpenAPI schema automatically; add explicit body matchers only when asserting a specific field value (e.g. the discriminator property came back correctly)

5. Output format

Always produce:

1. Analysis — number of status codes, which schemas are polymorphic, how many tests will be generated and why
2. Drift operations YAML — the complete operations: block, ready to paste
3. Dataset YAML (if needed) — the datasets: block for any referenced test data
4. Gaps — schema combinations intentionally excluded, with the reason

Example

Given GET /v2/images/{image_id} where 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