OpenApiGenerator

The OpenApiGenerator module orchestrates converting OpenAPI and Swagger documents into generated Effect source.

It normalizes Swagger 2.0 input, resolves local references, builds the parsed operation model, registers request and response schemas, applies HttpApi-specific adaptations such as multipart helpers and security metadata, emits warnings for unsupported or lossy OpenAPI features, and then delegates final rendering to the HttpClient or HttpApi code generators.

9 exports Since v4.0.0 Source

Constructors

make

Since v4.0.0

Constructs the OpenAPI generator service implementation.

Signature

declare const make: Effect<{
  generate: (...args: [_: OpenAPISpec, options: OpenApiGenerateOptions]) => Effect;
}, never, never>

Formatting

formatWarning

Since v4.0.0

Formats a generation warning as a single human-readable line.

Details

The line starts with WARNING [code], followed by the HTTP method, path and operation id when the warning carries them, then the warning message.

Signature

declare function formatWarning(warning: OpenApiGeneratorWarning): string

Example Formatting an operation warning

import { formatWarning } from "@effect/openapi-generator/OpenApiGenerator"

formatWarning({
  code: "cookie-parameter-dropped",
  message: "Cookie parameter was dropped.",
  path: "/items",
  method: "get",
  operationId: "listItems"
}) // => "WARNING [cookie-parameter-dropped] GET /items (listItems): Cookie parameter was dropped."

Layers

layerTransformerSchema

Since v4.0.0

Layer providing an OpenAPI generator for Schema-backed HTTP client and HttpApi output.

Signature

declare const layerTransformerSchema: Layer.Layer<OpenApiGenerator>

layerTransformerTs

Since v4.0.0

Layer providing an OpenAPI generator for type-only HTTP client output.

Signature

declare const layerTransformerTs: Layer.Layer<OpenApiGenerator>

Models

OpenApiGeneratorFormat

type

Since v4.0.0

Output targets supported by the OpenAPI generator.

Details

The httpclient and httpclient-type-only formats support non-security cookie parameters with primitive schemas, which generated clients send in the request Cookie header. Cookie parameters with structured schemas, such as objects or arrays, are dropped with a cookie-parameter-dropped warning. The httpapi format drops all non-security cookie parameters.

The Cookie header is set before the request reaches the supplied HttpClient, so it is subject to that client's request transformations. Browsers manage the Cookie header themselves and ignore explicit values, and HttpClient.withCookiesRef replaces the header whenever its cookie jar is non-empty.

Signature

type OpenApiGeneratorFormat = "httpclient" | "httpclient-type-only" | "httpapi"

OpenApiGeneratorWarning

interface

Since v4.0.0

Describes a non-fatal issue encountered while mapping an OpenAPI operation to generated Effect source.

Signature

interface OpenApiGeneratorWarning {
  readonly code: OpenApiGeneratorWarningCode;
  readonly message: string;
  readonly method?: "get" | "post" | "put" | "delete" | "patch" | "head" | "options" | "trace" | "query";
  readonly operationId?: string;
  readonly path?: string;
}

OpenApiGeneratorWarningCode

type

Since v4.0.0

Stable identifiers for non-fatal OpenAPI generation warnings.

Signature

type OpenApiGeneratorWarningCode = "cookie-parameter-dropped" | "additional-tags-dropped" | "sse-operation-skipped" | "response-headers-ignored" | "optional-request-body-approximated" | "default-response-remapped" | "security-and-downgraded" | "no-body-method-request-body-skipped" | "streaming-request-body-skipped" | "naming-collision"

Options

OpenApiGenerateOptions

interface

Since v4.0.0

Options that control one OpenAPI generation run.

Signature

interface OpenApiGenerateOptions {
  readonly format: OpenApiGeneratorFormat;
  readonly name: string;
  readonly onEnter?: (js: JsonSchema) => JsonSchema;
  readonly onWarning?: (warning: OpenApiGeneratorWarning) => void;
}

Services

OpenApiGenerator

Since v4.0.0

Service for turning OpenAPI or Swagger specifications into generated Effect HTTP client or HttpApi source code.

Signature

declare class OpenApiGenerator extends Shape<"OpenApiGenerator", {
  readonly generate: (spec: OpenAPISpec, options: OpenApiGenerateOptions) => Effect<string>;
}, this> {
  constructor(_: never);
}