openapi-parser skill

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