# @askrjs/server/openapi

> Published API exports for @askrjs/server/openapi.

Source: [https://askrjs.com/docs/reference/api/server/openapi](https://askrjs.com/docs/reference/api/server/openapi)

Status: stable. Packages: @askrjs/server/openapi.

**Published packages are authoritative.** Examples may lag behind a published contract. When guidance differs, verify the exports and TypeScript declarations in your installed package, then file an issue.

## Exports

This entrypoint publishes 19 exports from the declarations shipped by @askrjs/server.

### `ApiDefinition`

```ts
ApiDefinition: any
```

The 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;

### `ApiGroup`

```ts
ApiGroup: any
```

A 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>;

### `ApiHandler`

```ts
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`.

### `ApiInfo`

```ts
ApiInfo: any
```

The 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;

### `ApiInput`

```ts
ApiInput: any
```

Declares 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;

### `ApiOperation`

```ts
ApiOperation: any
```

A 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>;

### `ApiOptions`

```ts
ApiOptions: any
```

Options 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.

### `BodyOptions`

```ts
BodyOptions: any
```

Metadata for a request body, used to enrich the generated OpenAPI document.

- `required`: required?: boolean;

- `description`: description?: string;

- `examples`: examples?: Record<string, unknown>;

### `createApi`

```ts
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`).

### `InferSchema`

```ts
InferSchema: T extends Schema<infer Value> ? Value : never
```

Infers the parsed value type of a {@link Schema}.

### `OpenApiDocument`

```ts
OpenApiDocument: any
```

A 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;

### `ParameterOptions`

```ts
ParameterOptions: any
```

Metadata 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;

### `ResponseOptions`

```ts
ResponseOptions: any
```

Metadata 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>;

### `RouteBuilder`

```ts
RouteBuilder: any
```

Fluent 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>;

### `schema`

```ts
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.

```tsx
const user = schema.object({ id: schema.uuid(), name: schema.string({ minLength: 1 }) });
const result = user.safeParse({ id: "...", name: "Ada" });
```

### `Schema`

```ts
Schema: any
```

An 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.

### `security`

```ts
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.

### `SecurityRequirement`

```ts
SecurityRequirement: readonly SecurityRequirementObject[]
```

An OpenAPI security requirement (a list of alternative scheme+scopes requirements), as built by the {@link security } helpers.

### `SecurityScheme`

```ts
SecurityScheme: Readonly<Record<string, unknown>>
```

An OpenAPI security scheme definition, as built by the {@link security } helpers.

## Documentation navigation

[Previous](https://askrjs.com/docs/reference/api/server/auth/index.md) | [Next](https://askrjs.com/docs/reference/api/server/mcp/index.md)