Askr
Server & APIs

OpenAPI

Use openapi with the current published Askr packages.

  • @askrjs/server/openapi0.0.3
  • @askrjs/cli0.0.5

How to use openapi

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/server/openapi and @askrjs/cli entrypoint.
  2. Keep openapi 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

Authoring operations

createApi<Dependencies>({ info, securitySchemes, servers, validateResponses }) from @askrjs/server/openapi returns an ApiDefinition you register routes on with .get(), .post(), and the rest, chaining .pathParam(), .queryParam(), .jsonBody(), .ok(), .notFound(), and similar calls to attach both the handler and its documented shape in the same fluent statement. .access(requirement, security) attaches an AuthRequirement from @askrjs/auth alongside the OpenAPI security requirement it maps to, so authorization and documentation stay one declaration instead of two.

jsonSchema contract

api.schema("Name", schema.object({...})) registers a reusable named component: its jsonSchema is projected into the document's components.schemas section, while the original @askrjs/schema parser keeps validating request and response bodies against it at runtime. Reusing the same registered schema across multiple routes keeps the generated document's component references consistent instead of duplicating inline schemas.

Generate and check

api.toOpenApiDocument() builds a deterministic, deeply frozen OpenAPI 3.1.2 document and refuses to generate one for an incomplete contract — missing or duplicate operationIds, undocumented responses, mismatched path parameters, wildcards, or unresolved schema and security references all fail the call outright. The askr openapi CLI command (askr openapi --entry src/api.ts --output ./openapi.yml) writes that document as YAML, and askr openapi --check performs no writes and exits unsuccessfully if the file is missing or differs by even one byte.

Client generation

There is no separate code-generation step for consuming the API from this stack: the same defineApi() descriptors from @askrjs/fetch that back a typed client are written by hand to mirror the routes registered with createApi(), so both sides of the contract get independent, statically-checked types without a generated intermediate artifact. The OpenAPI YAML that askr openapi produces is still useful as a portable contract for external tooling or generators outside the Askr toolchain.