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 specsreferences/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
