@btravstack/orpc-server

---

@btravstack/orpc-server / openapi

openapi

Type Aliases

OpenApiDocument

type OpenApiDocument = Awaited<ReturnType<OpenAPIGenerator["generate"]>>;

Defined in: orpc-server/src/openapi.ts:21

The OpenAPI document, as @orpc/openapi returns it.

Exported so a consumer can name it. Its constituent types come from a transitive OpenAPI specification package nothing here depends on directly, so an application annotating nothing gets TS4023 in its own declaration emit — measured on examples/order-api. Re-exporting the alias gives that application a name it owns a path to.

---

OpenApiOptions

type OpenApiOptions = object;

Defined in: orpc-server/src/openapi.ts:32

Properties

Property	Modifier	Type	Description	Defined in
base?	readonly	NonNullable<Parameters<OpenAPIGenerator["generate"]>[1]>["base"]	Merged into the document — info, servers, and anything else OpenAPI takes.	orpc-server/src/openapi.ts:46
securitySchemes?	readonly	Readonly<OpenApiSecuritySchemes>	What each scheme the contract names actually IS — { type: "http", scheme: "bearer" } and the like, verbatim into components.securitySchemes. The split is the same one defineHttp({ authenticators }) makes, and for the same reason: the contract says WHICH schemes protect a route, and it deliberately says nothing about what they resolve to. A scheme named by the contract with no definition here still appears in security — a reader of the document sees the requirement and an unresolvable reference, which is a louder fault than silently dropping the requirement.	orpc-server/src/openapi.ts:44

---

OpenApiRoutesOptions

type OpenApiRoutesOptions = Omit<OrpcOptions, "prefix" | "bodyLimit" | "csrf"> & object;

Defined in: orpc-server/src/openapi-routes.ts:24

Answerer-local policies; body limits and CSRF belong to the HTTP module.

Type Declaration

Name	Type	Description	Defined in
prefix?	`/${string}`	Where ordinary method-and-path requests are served. Default /api.	orpc-server/src/openapi-routes.ts:26

---

OpenApiSecuritySchemes

type OpenApiSecuritySchemes = NonNullable<NonNullable<OpenApiDocument["components"]>["securitySchemes"]>;

Defined in: orpc-server/src/openapi.ts:28

The document's own components.securitySchemes shape, reached by index off OpenApiDocument for the same TS4023 reason that alias exists: the real type lives in a transitive OpenAPI specification package.

Functions

openApiDocument()

function openApiDocument(contract, options?): AsyncResult<OpenAPIObject | OpenAPIObject | OpenAPIObject, never>;

Defined in: orpc-server/src/openapi.ts:121

The contract as an OpenAPI document, with the @btravstack/contract marker folded into each operation's security. Each procedure's .errors(...) entries may declare an integer HTTP error status in 400–599; the generated responses use those local statuses, as openApiRoutes does.

const document = (
  await openApiDocument(contract, {
    base: { info: { title: "Orders", version: "1.0.0" } },
    securitySchemes: { user: { type: "http", scheme: "bearer" } },
  })
).get();

The marker IS OpenAPI's shape, which is why this is a fold rather than a translation: Requirement is Record<scheme, scopes[]> and Requirements is an array of them — exactly SecurityRequirementObject[], where keys within one object are AND and separate objects are OR. That correspondence is the reason @btravstack/contract refuses a two-scheme requirement it would otherwise run as OR.

Operations are matched by operationId, and the walk computes it the way the generator does — @orpc/openapi's own getOpenAPIMeta, then meta?.operationId ?? path.join(".") — so a procedure that sets an operationId of its own is matched by that id rather than missed. Keying on the contract path alone published every such operation with no security, which reads as public.

A procedure that replaces the whole operation with .route({ spec }) owns its security too. An object spec is the operation, so there is nothing for this fold to add to; a function spec is handed the built operation and can drop what this wrote. Neither is guessed at.

Parameters

Parameter	Type
contract	Record<string, RouterContract>
options	OpenApiOptions

Returns

AsyncResult<OpenAPIObject | OpenAPIObject | OpenAPIObject, never>

---

openApiRoutes()

function openApiRoutes(options?): Provider<HttpHandler, never, 
  | HttpConfig
  | Observers
  | PortInstance<"OrpcRouter", Router<Record<never, never>>>> & object;

Defined in: orpc-server/src/openapi-routes.ts:34

Serve a contract's OpenAPI routes through the same router and HTTP runtime as RPC. Declared errors use the matched procedure's .errors(...) entry's integer status in 400–599, falling back to oRPC's mapping when absent.

Parameters

Parameter	Type
options	OpenApiRoutesOptions

Returns

Provider<HttpHandler, never, | HttpConfig | Observers | PortInstance<"OrpcRouter", Router<Record<never, never>>>> & object