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

Grep for Foo: in the spec to find its definition block
If Foo itself contains refs, resolve those too
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:

Analysis — number of status codes, which schemas are polymorphic, how many tests will be generated and why
Drift operations YAML — the complete operations: block, ready to paste
Dataset YAML (if needed) — the datasets: block for any referenced test data
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

openapi-parser