@askrjs/server/openapi
Exports from the declarations published in @askrjs/server. Signatures reflect the published artifact.
Exports
This entrypoint publishes 12 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.
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.
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).
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;
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>;
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.