Askr
Tooling

OpenAPI and Typed-Client Generation

Use openapi and typed-client generation with the current published Askr packages.

  • @askrjs/askr0.0.59

How to use openapi and typed-client generation

Generate the OpenAPI artifact from executable route schemas, check it for drift in CI, then generate the typed client from that checked artifact.

  1. Import the published @askrjs/askr entrypoint.
  2. Keep openapi and typed-client generation configuration next to the component, route, or server composition root that owns it.
  3. Handle pending, unavailable, cancellation, and failure states, then verify the production path.
askr openapi --output ./openapi.yaml
askr openapi --check --output ./openapi.yaml
askr generate ./openapi.yaml --output ./generated/api.ts

Generate OpenAPI

askr openapi [--entry <path>] [--output <path>] loads a TypeScript module (default src/api.ts) whose default export exposes a toOpenApiDocument() method, and writes the result as deterministic YAML (default ./openapi.yml) atomically. Because the output is deterministic, running it twice against unchanged source produces byte-identical files, which is what makes the --check mode below meaningful.

Check drift

askr openapi --check performs no writes at all: it exits unsuccessfully if the target YAML file is missing, or if it differs from the freshly generated document by even a single byte. That makes it a direct fit for a CI gate that fails a build the moment someone changes API-affecting code without regenerating and committing the artifact.

Generate a client

askr generate produces an @askrjs/fetch typed client from an OpenAPI document, separate from the openapi command itself. Where askr openapi produces the contract, askr generate consumes it -- the natural sequence in a project is to regenerate the OpenAPI artifact first, then regenerate the client against it, so the two stay in lockstep.

CI contract

A typical CI setup runs askr openapi --check as a required step before merge, so any handler or type change that shifts the API surface without a matching openapi.yml commit fails loudly. Because --entry and --output both have sane defaults (src/api.ts and ./openapi.yml), most projects don't need to pass any flags at all in the CI step -- the command only needs overrides when the API module or artifact path differs from convention.