Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

OpenApi unstable

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.

39 exports Since v4.0.0 Source

Annotations

annotations

unstable
Since v4.0.0

Builds a Context containing OpenAPI annotations from the supplied options.

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

fromApi

unstable
Since v4.0.0

Generates an OpenAPI 3.1 specification from an HttpApi.

When to use

Use when you need a programmatic OpenAPI document for an API definition.

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. The optional reference policy receives canonical JSON encoded ASTs and controls which schemas are extracted into components. By default, only candidates with resolved identifiers become references; anonymous non-recursive schemas remain inline.

Gotchas

Cached results are keyed by both the HttpApi instance and the identity of the options object. Reuse the same immutable options object to reuse a cached result; mutating an options object after its first use does not invalidate the cached specification. Each call returns a copy of the cached specification.

Signature

declare function fromApi<Id extends string, Groups extends Constraint>(api: HttpApi<Id, Groups>, options?: ToRepresentationOptions): OpenAPISpec

Models

OpenAPIApiKeySecurityScheme

interface unstable
Since v4.0.0

Generated OpenAPI API key security scheme.

Signature

interface OpenAPIApiKeySecurityScheme {
  description?: string;
  in: "query" | "header" | "cookie";
  name: string;
  readonly type: "apiKey";
}

OpenAPIComponents

interface unstable
Since v4.0.0

Generated OpenAPI components containing shared schemas and security schemes.

Signature

interface OpenAPIComponents {
  schemas: Definitions;
  securitySchemes: Record<string, OpenAPISecurityScheme>;
}

OpenAPIHTTPSecurityScheme

interface unstable
Since v4.0.0

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 unstable
Since v4.0.0

Generated OpenAPI security requirement, keyed by security scheme name.

Signature

type OpenAPISecurityRequirement = Record<string, Array<string>>

OpenAPISecurityScheme

type unstable
Since v4.0.0

Union of security scheme objects emitted in generated OpenAPI components.

Signature

type OpenAPISecurityScheme = OpenAPIHTTPSecurityScheme | OpenAPIApiKeySecurityScheme

OpenAPISpec

interface unstable
Since v4.0.0

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 unstable
Since v4.0.0

Generated OpenAPI content object, keyed by media type.

Signature

type OpenApiSpecContent = { [K in string]: OpenApiSpecMediaType }

OpenApiSpecEffectStream

type unstable
Since v4.0.0

Effect-specific metadata for generated streaming response media types.

Signature

type OpenApiSpecEffectStream = {
  causeSchema: JsonSchema.JsonSchema;
  encoding: "sse";
  errorSchema: JsonSchema.JsonSchema;
  failureEvent: "effect/http-api/stream/failure";
} | {
  encoding: "uint8array";
}

OpenAPISpecExternalDocs

interface unstable
Since v4.0.0

OpenAPI external documentation metadata.

Signature

interface OpenAPISpecExternalDocs {
  description?: string;
  url: string;
}

OpenAPISpecHeader

type unstable
Since v4.0.0

Generated OpenAPI response header object.

Signature

type OpenAPISpecHeader = Omit<OpenAPISpecParameter, "name" | "in">

OpenAPISpecInfo

interface unstable
Since v4.0.0

OpenAPI info object generated by fromApi.

Signature

interface OpenAPISpecInfo {
  description?: string;
  license?: OpenAPISpecLicense;
  summary?: string;
  title: string;
  version: string;
}

OpenAPISpecLicense

interface unstable
Since v4.0.0

OpenAPI license metadata used in the generated info object.

Signature

interface OpenAPISpecLicense {
  [key: string]: unknown;
  name: string;
  url?: string;
}

OpenApiSpecMediaType

interface unstable
Since v4.0.0

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 unstable
Since v4.0.0

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 unstable
Since v4.0.0

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 unstable
Since v4.0.0

Generated OpenAPI parameter object for path, query, header, or cookie parameters.

Signature

interface OpenAPISpecParameter {
  description?: string;
  in: "query" | "path" | "header" | "cookie";
  name: string;
  required: boolean;
  schema: object;
}

OpenAPISpecPathItem

type unstable
Since v4.0.0

Generated OpenAPI path item mapping HTTP methods to operations for a single route path. Parameters declared here are shared by every operation on the path. QUERY operations are emitted under x-oai-additionalOperations.

Signature

type OpenAPISpecPathItem = { [K in OpenAPISpecMethodName]: OpenAPISpecOperation } & {
  parameters?: Array<OpenAPISpecParameter>;
  "x-oai-additionalOperations"?: Partial<Record<HttpMethod.HttpMethod, OpenAPISpecOperation>>;
}

OpenAPISpecPaths

type unstable
Since v4.0.0

Generated OpenAPI paths object, keyed by route path.

Signature

type OpenAPISpecPaths = Record<string, OpenAPISpecPathItem>

OpenAPISpecRequestBody

interface unstable
Since v4.0.0

Generated OpenAPI request body object for endpoint payloads.

Signature

interface OpenAPISpecRequestBody {
  content: OpenApiSpecContent;
  required: true;
}

OpenApiSpecResponse

interface unstable
Since v4.0.0

Generated OpenAPI response object for an endpoint success or error schema.

Signature

interface OpenApiSpecResponse {
  content?: OpenApiSpecContent;
  description: string;
  headers?: Record<string, OpenAPISpecHeader>;
}

OpenAPISpecResponses

type unstable
Since v4.0.0

Generated OpenAPI responses object, keyed by HTTP status code.

Signature

type OpenAPISpecResponses = Record<number, OpenApiSpecResponse>

OpenAPISpecServer

interface unstable
Since v4.0.0

OpenAPI server object used in the generated servers array.

Signature

interface OpenAPISpecServer {
  description?: string;
  url: string;
  variables?: Record<string, OpenAPISpecServerVariable>;
}

OpenAPISpecServerVariable

interface unstable
Since v4.0.0

OpenAPI variable definition for templated server URLs.

Signature

interface OpenAPISpecServerVariable {
  default: string;
  description?: string;
  enum?: [string, ...Array<string>];
}

OpenAPISpecTag

interface unstable
Since v4.0.0

OpenAPI tag object generated for an HTTP API group.

Signature

interface OpenAPISpecTag {
  description?: string;
  externalDocs?: OpenAPISpecExternalDocs;
  name: string;
}

Services

Deprecated

unstable
Since v4.0.0

OpenAPI annotation for marking a generated endpoint operation as deprecated.

Signature

declare class Deprecated extends Shape<"effect/http-api/OpenApi/Deprecated", boolean, this> {
  constructor(_: never);
}

Description

unstable
Since v4.0.0

OpenAPI annotation for setting generated descriptions on APIs, groups, endpoints, or security schemes.

Signature

declare class Description extends Shape<"effect/http-api/OpenApi/Description", string, this> {
  constructor(_: never);
}

Exclude

unstable
Since v4.0.0

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

unstable
Since v4.0.0

OpenAPI annotation for adding external documentation metadata to groups or endpoints.

Signature

declare class ExternalDocs extends Shape<"effect/http-api/OpenApi/ExternalDocs", OpenAPISpecExternalDocs, this> {
  constructor(_: never);
}

Format

unstable
Since v4.0.0

OpenAPI annotation for setting the format metadata, such as a bearer token format on security schemes.

Signature

declare class Format extends Shape<"effect/http-api/OpenApi/Format", string, this> {
  constructor(_: never);
}

Identifier

unstable
Since v4.0.0

OpenAPI annotation for overriding generated identifiers, including operation ids.

Signature

declare class Identifier extends Shape<"effect/http-api/OpenApi/Identifier", string, this> {
  constructor(_: never);
}

License

unstable
Since v4.0.0

OpenAPI annotation for setting the generated API license metadata.

Signature

declare class License extends Shape<"effect/http-api/OpenApi/License", OpenAPISpecLicense, this> {
  constructor(_: never);
}

Override

unstable
Since v4.0.0

OpenAPI annotation for shallowly merging additional fields into a generated OpenAPI object.

Signature

declare class Override extends Shape<"effect/http-api/OpenApi/Override", Record<string, unknown>, this> {
  constructor(_: never);
}

Servers

unstable
Since v4.0.0

OpenAPI annotation for setting the generated API server list.

Signature

declare class Servers extends Shape<"effect/http-api/OpenApi/Servers", readonly Array<OpenAPISpecServer>, this> {
  constructor(_: never);
}

Summary

unstable
Since v4.0.0

OpenAPI annotation for setting generated summary text.

Signature

declare class Summary extends Shape<"effect/http-api/OpenApi/Summary", string, this> {
  constructor(_: never);
}

Title

unstable
Since v4.0.0

OpenAPI annotation for setting the API title or group tag name.

Signature

declare class Title extends Shape<"effect/http-api/OpenApi/Title", string, this> {
  constructor(_: never);
}

Transform

unstable
Since v4.0.0

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/http-api/OpenApi/Transform", (openApiSpec: Record<string, any>) => Record<string, any>, this> {
  constructor(_: never);
}

Version

unstable
Since v4.0.0

OpenAPI annotation for setting the generated API version.

Signature

declare class Version extends Shape<"effect/http-api/OpenApi/Version", string, this> {
  constructor(_: never);
}