OpenApi.ts

OpenApi.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• annotations
  • Deprecated (class)
  • Description (class)
  • Exclude
  • ExternalDocs (class)
  • Format (class)
  • Identifier (class)
  • License (class)
  • Override (class)
  • Servers (class)
  • Summary (class)
  • Title (class)
  • Transform (class)
  • Version (class)
  • annotations
• constructors
  • fromApi
• models
  • OpenAPIApiKeySecurityScheme (interface)
  • OpenAPIComponents (interface)
  • OpenAPIHTTPSecurityScheme (interface)
  • OpenAPISecurityRequirement (type alias)
  • OpenAPISecurityScheme (type alias)
  • OpenAPISpec (interface)
  • OpenAPISpecExternalDocs (interface)
  • OpenAPISpecInfo (interface)
  • OpenAPISpecLicense (interface)
  • OpenAPISpecMethodName (type alias)
  • OpenAPISpecOperation (interface)
  • OpenAPISpecParameter (interface)
  • OpenAPISpecPathItem (type alias)
  • OpenAPISpecPaths (type alias)
  • OpenAPISpecRequestBody (interface)
  • OpenAPISpecResponses (type alias)
  • OpenAPISpecServer (interface)
  • OpenAPISpecServerVariable (interface)
  • OpenAPISpecTag (interface)
  • OpenApiSpecContent (type alias)
  • OpenApiSpecEffectStream (type alias)
  • OpenApiSpecMediaType (interface)
  • OpenApiSpecResponse (interface)

---

annotations

Deprecated (class)

OpenAPI annotation for marking a generated endpoint operation as deprecated.

Signature

declare class Deprecated

Source

Since v4.0.0

Description (class)

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

Signature

declare class Description

Source

Since v4.0.0

Exclude

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: Context.Reference<boolean>

Source

Since v4.0.0

ExternalDocs (class)

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

Signature

declare class ExternalDocs

Source

Since v4.0.0

Format (class)

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

Signature

declare class Format

Source

Since v4.0.0

Identifier (class)

OpenAPI annotation for overriding generated identifiers, including operation ids.

Signature

declare class Identifier

Source

Since v4.0.0

License (class)

OpenAPI annotation for setting the generated API license metadata.

Signature

declare class License

Source

Since v4.0.0

Override (class)

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

Signature

declare class Override

Source

Since v4.0.0

Servers (class)

OpenAPI annotation for setting the generated API server list.

Signature

declare class Servers

Source

Since v4.0.0

Summary (class)

OpenAPI annotation for setting generated summary text.

Signature

declare class Summary

Source

Since v4.0.0

Title (class)

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

Signature

declare class Title

Source

Since v4.0.0

Transform (class)

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

Source

Since v4.0.0

Version (class)

OpenAPI annotation for setting the generated API version.

Signature

declare class Version

Source

Since v4.0.0

annotations

Builds a Context containing OpenAPI annotations from the supplied options.

Signature

declare const annotations: (options: {
  readonly identifier?: string | undefined
  readonly title?: string | undefined
  readonly version?: string | undefined
  readonly description?: string | undefined
  readonly license?: OpenAPISpecLicense | undefined
  readonly summary?: string | undefined
  readonly deprecated?: boolean | undefined
  readonly externalDocs?: OpenAPISpecExternalDocs | undefined
  readonly servers?: ReadonlyArray<OpenAPISpecServer> | undefined
  readonly format?: string | undefined
  readonly override?: Record<string, unknown> | undefined
  readonly exclude?: boolean | undefined
  readonly transform?: ((openApiSpec: Record<string, any>) => Record<string, any>) | undefined
}) => Context.Context<never>

Source

Since v4.0.0

constructors

fromApi

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 const fromApi: <Id extends string, Groups extends HttpApiGroup.Any>(
  api: HttpApi.HttpApi<Id, Groups>
) => OpenAPISpec

Source

Since v4.0.0

models

OpenAPIApiKeySecurityScheme (interface)

Generated OpenAPI API key security scheme.

Signature

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

Source

Since v4.0.0

OpenAPIComponents (interface)

Generated OpenAPI components containing shared schemas and security schemes.

Signature

export interface OpenAPIComponents {
  schemas: JsonSchema.Definitions
  securitySchemes: Record<string, OpenAPISecurityScheme>
}

Source

Since v4.0.0

OpenAPIHTTPSecurityScheme (interface)

Generated OpenAPI HTTP security scheme, such as bearer or basic authentication.

Signature

export interface OpenAPIHTTPSecurityScheme {
  readonly type: "http"
  scheme: "bearer" | "basic" | string
  description?: string
  /* only for scheme: 'bearer' */
  bearerFormat?: string
}

Source

Since v4.0.0

OpenAPISecurityRequirement (type alias)

Generated OpenAPI security requirement, keyed by security scheme name.

Signature

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

Source

Since v4.0.0

OpenAPISecurityScheme (type alias)

Union of security scheme objects emitted in generated OpenAPI components.

Signature

type OpenAPISecurityScheme = OpenAPIHTTPSecurityScheme | OpenAPIApiKeySecurityScheme

Source

Since v4.0.0

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

export interface OpenAPISpec {
  openapi: "3.1.0"
  info: OpenAPISpecInfo
  paths: OpenAPISpecPaths
  components: OpenAPIComponents
  security: Array<OpenAPISecurityRequirement>
  tags: Array<OpenAPISpecTag>
  servers?: Array<OpenAPISpecServer>
}

Source

Since v4.0.0

OpenAPISpecExternalDocs (interface)

OpenAPI external documentation metadata.

Signature

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

Source

Since v4.0.0

OpenAPISpecInfo (interface)

OpenAPI info object generated by fromApi.

Signature

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

Source

Since v4.0.0

OpenAPISpecLicense (interface)

OpenAPI license metadata used in the generated info object.

Signature

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

Source

Since v4.0.0

OpenAPISpecMethodName (type alias)

Lowercase HTTP method names used as keys in generated OpenAPI path items.

Signature

type OpenAPISpecMethodName = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace"

Source

Since v4.0.0

OpenAPISpecOperation (interface)

Generated OpenAPI operation object for an HTTP API endpoint.

Signature

export interface OpenAPISpecOperation {
  operationId: string
  parameters: Array<OpenAPISpecParameter>
  responses: OpenAPISpecResponses
  /** Always contains at least the title annotation or the group identifier */
  tags: NonEmptyArray<string>
  security: Array<OpenAPISecurityRequirement>
  requestBody?: OpenAPISpecRequestBody
  description?: string
  summary?: string
  deprecated?: boolean
  externalDocs?: OpenAPISpecExternalDocs
}

Source

Since v4.0.0

OpenAPISpecParameter (interface)

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

Signature

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

Source

Since v4.0.0

OpenAPISpecPathItem (type alias)

Generated OpenAPI path item mapping HTTP methods to operations for a single route path.

Signature

type OpenAPISpecPathItem = {
  [K in OpenAPISpecMethodName]?: OpenAPISpecOperation
}

Source

Since v4.0.0

OpenAPISpecPaths (type alias)

Generated OpenAPI paths object, keyed by route path.

Signature

type OpenAPISpecPaths = Record<string, OpenAPISpecPathItem>

Source

Since v4.0.0

OpenAPISpecRequestBody (interface)

Generated OpenAPI request body object for endpoint payloads.

Signature

export interface OpenAPISpecRequestBody {
  content: OpenApiSpecContent
  required: true
}

Source

Since v4.0.0

OpenAPISpecResponses (type alias)

Generated OpenAPI responses object, keyed by HTTP status code.

Signature

type OpenAPISpecResponses = Record<number, OpenApiSpecResponse>

Source

Since v4.0.0

OpenAPISpecServer (interface)

OpenAPI server object used in the generated servers array.

Signature

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

Source

Since v4.0.0

OpenAPISpecServerVariable (interface)

OpenAPI variable definition for templated server URLs.

Signature

export interface OpenAPISpecServerVariable {
  default: string
  enum?: NonEmptyArray<string>
  description?: string
}

Source

Since v4.0.0

OpenAPISpecTag (interface)

OpenAPI tag object generated for an HTTP API group.

Signature

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

Source

Since v4.0.0

OpenApiSpecContent (type alias)

Generated OpenAPI content object, keyed by media type.

Signature

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

Source

Since v4.0.0

OpenApiSpecEffectStream (type alias)

Effect-specific metadata for generated streaming response media types.

Signature

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

Source

Since v4.0.0

OpenApiSpecMediaType (interface)

Generated OpenAPI media type object containing the JSON Schema for a request or response body.

Signature

export interface OpenApiSpecMediaType {
  schema: JsonSchema.JsonSchema
  "x-effect-stream"?: OpenApiSpecEffectStream
}

Source

Since v4.0.0

OpenApiSpecResponse (interface)

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

Signature

export interface OpenApiSpecResponse {
  description: string
  content?: OpenApiSpecContent
}

Source

Since v4.0.0