OpenApi
Generates OpenAPI 3.1 documents from declarative HttpApi contracts.
The generator reads API groups, endpoints, schemas, security definitions, and annotations, then produces an OpenAPI document. This module also provides the annotations used to shape that output and the TypeScript model for the OpenAPI objects it generates.
Annotations
annotations
Signature
declare const annotations: (options: {
readonly deprecated?: boolean;
readonly description?: string;
readonly exclude?: boolean;
readonly externalDocs?: OpenAPISpecExternalDocs;
readonly format?: string;
readonly identifier?: string;
readonly license?: OpenAPISpecLicense;
readonly override?: Record<string, unknown>;
readonly servers?: ReadonlyArray<OpenAPISpecServer>;
readonly summary?: string;
readonly title?: string;
readonly transform?: (openApiSpec: Record<string, any>) => Record<string, any>;
readonly version?: string;
}) => Context.Context<never>;Constructors
Converts an HttpApi instance into an OpenAPI Specification object.
Details
This function takes an HttpApi instance, which defines a structured API, and generates an OpenAPI Specification (OpenAPISpec). The resulting spec adheres to the OpenAPI 3.1.0 standard and includes detailed metadata such as paths, operations, security schemes, and components. The function processes the API's annotations, middleware, groups, and endpoints to build a complete and accurate representation of the API in OpenAPI format.
The function also deduplicates schemas, applies transformations, and integrates annotations like descriptions, summaries, external documentation, and overrides. Cached results are used for better performance when the same HttpApi instance is processed multiple times.
Signature
declare function fromApi<Id extends string, Groups extends Constraint>(
api: HttpApi<Id, Groups>,
): OpenAPISpec;Models
OpenAPIApiKeySecurityScheme interface
Generated OpenAPI API key security scheme.
Signature
interface OpenAPIApiKeySecurityScheme {
description?: string;
in: "cookie" | "header" | "query";
name: string;
readonly type: "apiKey";
}OpenAPIComponents interface
Generated OpenAPI components containing shared schemas and security schemes.
Signature
interface OpenAPIComponents {
schemas: Definitions;
securitySchemes: Record<string, OpenAPISecurityScheme>;
}OpenAPIHTTPSecurityScheme interface
Generated OpenAPI HTTP security scheme, such as bearer or basic authentication.
Signature
interface OpenAPIHTTPSecurityScheme {
bearerFormat?: string;
description?: string;
scheme: string;
readonly type: "http";
}OpenAPISecurityRequirement type
Generated OpenAPI security requirement, keyed by security scheme name.
Signature
type OpenAPISecurityRequirement = Record<string, Array<string>>;OpenAPISecurityScheme type
Union of security scheme objects emitted in generated OpenAPI components.
Signature
type OpenAPISecurityScheme = OpenAPIHTTPSecurityScheme | OpenAPIApiKeySecurityScheme;OpenAPISpec interface
This model describes the OpenAPI specification (version 3.1.0) returned by fromApi. It is not intended to describe the entire OpenAPI specification, only the output of fromApi.
Signature
interface OpenAPISpec {
components: OpenAPIComponents;
info: OpenAPISpecInfo;
openapi: "3.1.0";
paths: OpenAPISpecPaths;
security: Array<OpenAPISecurityRequirement>;
servers?: Array<OpenAPISpecServer>;
tags: Array<OpenAPISpecTag>;
}OpenApiSpecContent type
Generated OpenAPI content object, keyed by media type.
Signature
type OpenApiSpecContent = { [K in string]: OpenApiSpecMediaType };OpenApiSpecEffectStream type
Effect-specific metadata for generated streaming response media types.
Signature
type OpenApiSpecEffectStream =
| {
causeSchema: JsonSchema.JsonSchema;
encoding: "sse";
errorSchema: JsonSchema.JsonSchema;
failureEvent: "effect/httpapi/stream/failure";
}
| {
encoding: "uint8array";
};OpenAPISpecExternalDocs interface
OpenAPI external documentation metadata.
Signature
interface OpenAPISpecExternalDocs {
description?: string;
url: string;
}OpenAPISpecHeader type
Generated OpenAPI response header object.
Signature
type OpenAPISpecHeader = Omit<OpenAPISpecParameter, "name" | "in">;OpenAPISpecInfo interface
OpenAPI info object generated by fromApi.
Signature
interface OpenAPISpecInfo {
description?: string;
license?: OpenAPISpecLicense;
summary?: string;
title: string;
version: string;
}OpenAPISpecLicense interface
OpenAPI license metadata used in the generated info object.
Signature
interface OpenAPISpecLicense {
[key: string]: unknown;
name: string;
url?: string;
}OpenApiSpecMediaType interface
Generated OpenAPI media type object containing the JSON Schema for a request or response body.
Signature
interface OpenApiSpecMediaType {
schema: JsonSchema;
"x-effect-stream"?: OpenApiSpecEffectStream;
}OpenAPISpecMethodName type
Lowercase HTTP method names used as keys in generated OpenAPI path items.
Signature
type OpenAPISpecMethodName =
| "get"
| "put"
| "post"
| "delete"
| "options"
| "head"
| "patch"
| "trace";OpenAPISpecOperation interface
Generated OpenAPI operation object for an HTTP API endpoint.
Signature
interface OpenAPISpecOperation {
deprecated?: boolean;
description?: string;
externalDocs?: OpenAPISpecExternalDocs;
operationId: string;
parameters: Array<OpenAPISpecParameter>;
requestBody?: OpenAPISpecRequestBody;
responses: OpenAPISpecResponses;
security: Array<OpenAPISecurityRequirement>;
summary?: string;
tags: [string, ...Array<string>];
}OpenAPISpecParameter interface
Generated OpenAPI parameter object for path, query, header, or cookie parameters.
Signature
interface OpenAPISpecParameter {
description?: string;
in: "path" | "cookie" | "header" | "query";
name: string;
required: boolean;
schema: object;
}OpenAPISpecPathItem type
Generated OpenAPI path item mapping HTTP methods to operations for a single route path.
Signature
type OpenAPISpecPathItem = { [K in OpenAPISpecMethodName]: OpenAPISpecOperation };OpenAPISpecPaths type
Generated OpenAPI paths object, keyed by route path.
Signature
type OpenAPISpecPaths = Record<string, OpenAPISpecPathItem>;OpenAPISpecRequestBody interface
Generated OpenAPI request body object for endpoint payloads.
Signature
interface OpenAPISpecRequestBody {
content: OpenApiSpecContent;
required: true;
}OpenApiSpecResponse interface
Generated OpenAPI response object for an endpoint success or error schema.
Signature
interface OpenApiSpecResponse {
content?: OpenApiSpecContent;
description: string;
headers?: Record<string, OpenAPISpecHeader>;
}OpenAPISpecResponses type
Generated OpenAPI responses object, keyed by HTTP status code.
Signature
type OpenAPISpecResponses = Record<number, OpenApiSpecResponse>;OpenAPISpecServer interface
OpenAPI server object used in the generated servers array.
Signature
interface OpenAPISpecServer {
description?: string;
url: string;
variables?: Record<string, OpenAPISpecServerVariable>;
}OpenAPISpecServerVariable interface
OpenAPI variable definition for templated server URLs.
Signature
interface OpenAPISpecServerVariable {
default: string;
description?: string;
enum?: [string, ...Array<string>];
}OpenAPISpecTag interface
OpenAPI tag object generated for an HTTP API group.
Signature
interface OpenAPISpecTag {
description?: string;
externalDocs?: OpenAPISpecExternalDocs;
name: string;
}Services
Deprecated
OpenAPI annotation for marking a generated endpoint operation as deprecated.
Signature
declare class Deprecated extends Shape<"effect/httpapi/OpenApi/Deprecated", boolean, this> {
constructor(_: never);
}Description
OpenAPI annotation for setting generated descriptions on APIs, groups, endpoints, or security schemes.
Signature
declare class Description extends Shape<"effect/httpapi/OpenApi/Description", string, this> {
constructor(_: never);
}Annotation that excludes an annotated group or endpoint from the generated OpenAPI specification.
When to use
Use to hide internal, experimental, or otherwise undocumented HTTP API groups and endpoints from generated OpenAPI output.
Signature
declare const Exclude: Reference<boolean>;ExternalDocs
OpenAPI annotation for adding external documentation metadata to groups or endpoints.
Signature
declare class ExternalDocs extends Shape<
"effect/httpapi/OpenApi/ExternalDocs",
OpenAPISpecExternalDocs,
this
> {
constructor(_: never);
}OpenAPI annotation for setting the format metadata, such as a bearer token format on security schemes.
Signature
declare class Format extends Shape<"effect/httpapi/OpenApi/Format", string, this> {
constructor(_: never);
}Identifier
OpenAPI annotation for overriding generated identifiers, including operation ids.
Signature
declare class Identifier extends Shape<"effect/httpapi/OpenApi/Identifier", string, this> {
constructor(_: never);
}OpenAPI annotation for setting the generated API license metadata.
Signature
declare class License extends Shape<"effect/httpapi/OpenApi/License", OpenAPISpecLicense, this> {
constructor(_: never);
}OpenAPI annotation for shallowly merging additional fields into a generated OpenAPI object.
Signature
declare class Override extends Shape<
"effect/httpapi/OpenApi/Override",
Record<string, unknown>,
this
> {
constructor(_: never);
}OpenAPI annotation for setting the generated API server list.
Signature
declare class Servers extends Shape<"effect/httpapi/OpenApi/Servers", readonly Array<OpenAPISpecServer>, this> {
constructor(_: never);
}OpenAPI annotation for setting generated summary text.
Signature
declare class Summary extends Shape<"effect/httpapi/OpenApi/Summary", string, this> {
constructor(_: never);
}OpenAPI annotation for setting the API title or group tag name.
Signature
declare class Title extends Shape<"effect/httpapi/OpenApi/Title", string, this> {
constructor(_: never);
}OpenAPI annotation for transforming a generated OpenAPI object.
Details
The function is applied during generation to the annotated API, group tag, or endpoint operation.
Signature
declare class Transform extends Shape<
"effect/httpapi/OpenApi/Transform",
(openApiSpec: Record<string, any>) => Record<string, any>,
this
> {
constructor(_: never);
}OpenAPI annotation for setting the generated API version.
Signature
declare class Version extends Shape<"effect/httpapi/OpenApi/Version", string, this> {
constructor(_: never);
}
Builds a
Contextcontaining OpenAPI annotations from the supplied options.