@askrjs/server/openapi
Exports from the declarations published in @askrjs/server. Signatures reflect the published artifact.
Exports
This entrypoint publishes 19 exports. Use the anchored symbol rows for direct links. Type-only exports are labeled separately from runtime values.
ApiDefinitiontype
ApiDefinition: anyThe root API definition returned by {@link createApi }: a top-level {@link ApiGroup} that can also register reusable named schemas, build a concrete {@link Router} from its routes, and render an {@link OpenApiDocument}.
schema- schema<const Value extends Schema>(name: string, value: Value): Value;
createRouter- createRouter: [Dependencies] extends [undefined] ? (dependencies?: undefined) => Router : (dependencies: Dependencies) => Router;
toOpenApiDocument- toOpenApiDocument(): OpenApiDocument;
ApiGrouptype
ApiGroup: anyA prefixed group of routes within an {@link ApiDefinition}, supporting nested sub-groups, shared tags/middleware/auth/params, and per-HTTP-method route registration.
tags- tags(...values: string[]): ApiGroup<Dependencies>;
use- use(...middleware: Middleware[]): ApiGroup<Dependencies>;
access- access(requirement: AuthRequirement, security: SecurityRequirement): ApiGroup<Dependencies>;
pathParam- pathParam(name: string, value: Schema, options?: ParameterOptions): ApiGroup<Dependencies>;
queryParam- queryParam(name: string, value: Schema, options?: ParameterOptions): ApiGroup<Dependencies>;
headerParam- headerParam(name: string, value: Schema, options?: ParameterOptions): ApiGroup<Dependencies>;
cookieParam- cookieParam(name: string, value: Schema, options?: ParameterOptions): ApiGroup<Dependencies>;
group- group<const Child extends string>(prefix: Child): ApiGroup<Dependencies, JoinPath<Prefix, Child>>;
get- get: ApiMethod<Dependencies, Prefix>;
post- post: ApiMethod<Dependencies, Prefix>;
put- put: ApiMethod<Dependencies, Prefix>;
patch- patch: ApiMethod<Dependencies, Prefix>;
delete- delete: ApiMethod<Dependencies, Prefix>;
options- options: ApiMethod<Dependencies, Prefix>;
head- head: ApiMethod<Dependencies, Prefix>;
trace- trace: ApiMethod<Dependencies, Prefix>;
ApiHandlertype
ApiHandler: {
bivarianceHack(context: ServerContext<RouteParams>, dependencies: Dependencies): Response | Promise<Response>;
}["bivarianceHack"]A plain route handler registered via an {@link ApiGroup } method, receiving the resolved `dependencies`.
ApiInfotype
ApiInfo: anyThe OpenAPI `info` object: title, version, and descriptive metadata for the API.
title- readonly title: string;
version- readonly version: string;
summary- readonly summary?: string;
description- readonly description?: string;
termsOfService- readonly termsOfService?: string;
contact- readonly contact?: ContactObject;
license- readonly license?: LicenseObject;
ApiInputtype
ApiInput: anyDeclares the schemas for a route's inputs (path params, query, headers, body).
params- readonly params?: ObjectSchema;
query- readonly query?: ObjectSchema;
headers- readonly headers?: ObjectSchema;
body- readonly body?: ApiBodyInput;
ApiOperationtype
ApiOperation: anyA schema-typed route registered via an {@link ApiGroup } method: declares its `input` schemas (validated and bound before `handler` runs, with results typed via {@link InferApiInput}) and optional extra `documentation` for parameters/body not otherwise inferable.
input- readonly input?: Input;
documentation- readonly documentation?: InputDocumentation;
handler- readonly handler: (context: ServerContext<RouteParams>, input: InferApiInput<Input>, dependencies: Dependencies) => Response | Promise<Response>;
ApiOptionstype
ApiOptions: anyOptions for {@link createApi }.
info- readonly info: ApiInfo;
metadata- Infer registration-safe metadata, or require fully authored public contracts.
servers- readonly servers?: readonly ServerObject[];
externalDocs- readonly externalDocs?: ExternalDocumentationObject;
securitySchemes- readonly securitySchemes?: Readonly<Record<string, SecurityScheme>>;
validateResponses- Validate documented response bodies only when explicitly enabled outside production.
BodyOptionstype
BodyOptions: anyMetadata for a request body, used to enrich the generated OpenAPI document.
required- required?: boolean;
description- description?: string;
examples- examples?: Record<string, unknown>;
createApitype
createApi: <Dependencies = undefined>(options: ApiOptions) => ApiDefinition<Dependencies>Creates an OpenAPI-aware {@link ApiDefinition}: a schema-typed route builder that records operation metadata and input/response schemas as routes are registered, then can render the routes as a concrete {@link Router } (`createRouter`) or as an OpenAPI document (`toOpenApiDocument`).
InferSchematype
InferSchema: T extends Schema<infer Value> ? Value : neverInfers the parsed value type of a {@link Schema}.
OpenApiDocumenttype
OpenApiDocument: anyA complete OpenAPI 3.1 document, as produced by {@link ApiDefinition.toOpenApiDocument }.
openapi- readonly openapi: "3.1.2";
info- readonly info: ApiInfo;
servers- readonly servers?: readonly ServerObject[];
paths- readonly paths: Readonly<Record<string, PathItemObject>>;
components- readonly components: ComponentsObject;
externalDocs- readonly externalDocs?: ExternalDocumentationObject;
ParameterOptionstype
ParameterOptions: anyMetadata for a path/query/header/cookie parameter, used to enrich the generated OpenAPI document.
description- description?: string;
required- required?: boolean;
deprecated- deprecated?: boolean;
example- example?: unknown;
ResponseOptionstype
ResponseOptions: anyMetadata for a response, used to enrich the generated OpenAPI document.
description- description?: string;
mediaType- mediaType?: string;
headers- headers?: Record<string, unknown>;
examples- examples?: Record<string, unknown>;
RouteBuildertype
RouteBuilder: anyFluent builder for describing a single route's OpenAPI operation: metadata (operation ID, summary, tags), request inputs (path/query/header/cookie params and body), and possible responses (both status-coded shorthand methods like `ok`/`notFound` and the generic `response`).
operationId- operationId(value: string): RouteBuilder<Dependencies>;
summary- summary(value: string): RouteBuilder<Dependencies>;
description- description(value: string): RouteBuilder<Dependencies>;
tags- tags(...values: string[]): RouteBuilder<Dependencies>;
deprecated- deprecated(value?: boolean): RouteBuilder<Dependencies>;
externalDocs- externalDocs(url: string, description?: string): RouteBuilder<Dependencies>;
use- use(...middleware: Middleware[]): RouteBuilder<Dependencies>;
maxRequestBytes- maxRequestBytes(bytes: number): RouteBuilder<Dependencies>;
access- access(requirement: AuthRequirement, security: SecurityRequirement): RouteBuilder<Dependencies>;
pathParam- pathParam(name: string, value: Schema, options?: ParameterOptions): RouteBuilder<Dependencies>;
queryParam- queryParam(name: string, value: Schema, options?: ParameterOptions): RouteBuilder<Dependencies>;
headerParam- headerParam(name: string, value: Schema, options?: ParameterOptions): RouteBuilder<Dependencies>;
cookieParam- cookieParam(name: string, value: Schema, options?: ParameterOptions): RouteBuilder<Dependencies>;
jsonBody- jsonBody(value: Schema, options?: BodyOptions): RouteBuilder<Dependencies>;
formBody- formBody(value: Schema, options?: BodyOptions): RouteBuilder<Dependencies>;
multipartBody- multipartBody(value: Schema, options?: BodyOptions): RouteBuilder<Dependencies>;
body- body(mediaType: string, value: Schema, options?: BodyOptions): RouteBuilder<Dependencies>;
response- response(status: number | string, value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
ok- ok(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
created- created(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
accepted- accepted(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
noContent- noContent(options?: ResponseOptions): RouteBuilder<Dependencies>;
movedPermanently- movedPermanently(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
found- found(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
seeOther- seeOther(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
temporaryRedirect- temporaryRedirect(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
permanentRedirect- permanentRedirect(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
badRequest- badRequest(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
unauthorized- unauthorized(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
forbidden- forbidden(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
notFound- notFound(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
conflict- conflict(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
unprocessableEntity- unprocessableEntity(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
tooManyRequests- tooManyRequests(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
methodNotAllowed- methodNotAllowed(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
internalServerError- internalServerError(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
notImplemented- notImplemented(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
serviceUnavailable- serviceUnavailable(value?: Schema, options?: ResponseOptions): RouteBuilder<Dependencies>;
schematype
schema: Readonly<{ string: typeof string; uuid: (options?: StringOptions) => Schema<string>; email: (options?: StringOptions) => Schema<string>; uri: (options?: StringOptions) => Schema<string>; date: (options?: StringOptions) => Schema<string>; dateTime: (options?: StringOptions) => Schema<string>; byte: (options?: StringOptions) => Schema<string>; binary: (options?: StringOptions) => Schema<string>; number: (options?: NumberOptions) => Schema<number>; integer: (options?: NumberOptions) => Schema<number>; boolean: (options?: CommonOptions) => Schema<boolean>; null: (options?: CommonOptions) => Schema<null>; object: typeof object; array: typeof array; record: <T>(values: Schema<T>, options?: CommonOptions) => ObjectSchema<Record<string, T>>; enum: <const T extends readonly (string | number | boolean)[]>(values: T, options?: CommonOptions) => Schema<T[number]>; literal: <const T extends string | number | boolean | null>(value: T, options?: CommonOptions) => Schema<T>; optional: <T>(value: Schema<T>) => OptionalSchema<T>; nullable: <T extends Schema>(value: T) => NullableSchema<T>; oneOf: <const T extends readonly Schema[]>(...values: T) => Schema<InferSchema<T[number]>>; anyOf: <const T extends readonly Schema[]>(...values: T) => Schema<InferSchema<T[number]>>; allOf: <const T extends readonly Schema[]>(...values: T) => Schema<UnionToIntersection<InferSchema<T[number]>>>; raw: <T>(jsonSchema: JsonSchema, safeParse: (value: unknown) => SafeParseResult<T>) => Schema<T>; }>The public schema builder namespace: create executable schemas whose {@link Schema.safeParse} validates a value and whose `jsonSchema` field is a deterministic JSON Schema (draft 2020-12) projection suitable for OpenAPI documents.
const user = schema.object({ id: schema.uuid(), name: schema.string({ minLength: 1 }) });
const result = user.safeParse({ id: "...", name: "Ada" });Schematype
Schema: anyAn executable schema: carries its JSON Schema projection and a runtime parser.
jsonSchema- The deterministic JSON Schema (draft 2020-12) projection of this schema.
__type- Phantom type marker only; never set at runtime.
safeParse- Validates `value`, returning either the parsed data or a list of issues.
securitytype
security: Readonly<{ httpBearer(options?: { bearerFormat?: string; description?: string; }): SecurityScheme; httpBasic(options?: { description?: string; }): SecurityScheme; apiKey(name: string, location?: "header" | "query" | "cookie", options?: { description?: string; }): SecurityScheme; oauth2(flows: Record<string, unknown>, description?: string): SecurityScheme; openIdConnect(openIdConnectUrl: string, description?: string): SecurityScheme; require(name: string, scopes?: readonly string[]): SecurityRequirement; any(...requirements: readonly SecurityRequirement[]): SecurityRequirement; none(): SecurityRequirement; }>Helpers for building OpenAPI security schemes and requirements, used with `ApiGroup.access`/`RouteBuilder.access` to describe an operation's authentication needs.
SecurityRequirementtype
SecurityRequirement: readonly SecurityRequirementObject[]An OpenAPI security requirement (a list of alternative scheme+scopes requirements), as built by the {@link security } helpers.
SecuritySchemetype
SecurityScheme: Readonly<Record<string, unknown>>An OpenAPI security scheme definition, as built by the {@link security } helpers.