Skip to main content Link Search Menu Expand Document (external link)
effect

OpenApi.ts overview

Since v1.0.0

Exports Grouped by Category

annotations

Deprecated (class)

Signature

declare class Deprecated

Source

Since v1.0.0

Description (class)

Signature

declare class Description

Source

Since v1.0.0

Exclude (class)

Signature

declare class Exclude

Source

Since v1.0.0

ExternalDocs (class)

Signature

declare class ExternalDocs

Source

Since v1.0.0

Format (class)

Signature

declare class Format

Source

Since v1.0.0

Identifier (class)

Signature

declare class Identifier

Source

Since v1.0.0

License (class)

Signature

declare class License

Source

Since v1.0.0

Override (class)

Signature

declare class Override

Source

Since v1.0.0

Servers (class)

Signature

declare class Servers

Source

Since v1.0.0

Summary (class)

Signature

declare class Summary

Source

Since v1.0.0

Title (class)

Signature

declare class Title

Source

Since v1.0.0

Transform (class)

Transforms the generated OpenAPI specification

Signature

declare class Transform

Source

Since v1.0.0

Version (class)

Signature

declare class Version

Source

Since v1.0.0

annotations

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 v1.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.

Options

  • additionalPropertiesStrategy: Controls the handling of additional properties. Possible values are:
    • "strict": Disallow additional properties (default behavior).
    • "allow": Allow additional properties.

Example

import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "@effect/platform"
import { Schema } from "effect"

const api = HttpApi.make("api").add(
  HttpApiGroup.make("group").add(HttpApiEndpoint.get("get", "/items").addSuccess(Schema.Array(Schema.String)))
)

const spec = OpenApi.fromApi(api)

console.log(JSON.stringify(spec, null, 2))
// Output: OpenAPI specification in JSON format

Signature

declare const fromApi: <Id extends string, Groups extends HttpApiGroup.Any, E, R>(
  api: HttpApi.HttpApi<Id, Groups, E, R>,
  options?: { readonly additionalPropertiesStrategy?: AdditionalPropertiesStrategy | undefined } | undefined
) => OpenAPISpec

Source

Since v1.0.0

models

AdditionalPropertiesStrategy (type alias)

Signature

type AdditionalPropertiesStrategy = "allow" | "strict"

Source

Since v1.0.0

OpenAPIApiKeySecurityScheme (interface)

Signature

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

Source

Since v1.0.0

OpenAPIComponents (interface)

Signature

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

Source

Since v1.0.0

OpenAPIHTTPSecurityScheme (interface)

Signature

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

Source

Since v1.0.0

OpenAPISecurityRequirement (type alias)

Signature

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

Source

Since v1.0.0

OpenAPISecurityScheme (type alias)

Signature

type OpenAPISecurityScheme = OpenAPIHTTPSecurityScheme | OpenAPIApiKeySecurityScheme

Source

Since v1.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 v1.0.0

OpenAPISpecExternalDocs (interface)

Signature

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

Source

Since v1.0.0

OpenAPISpecInfo (interface)

Signature

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

Source

Since v1.0.0

OpenAPISpecLicense (interface)

Signature

export interface OpenAPISpecLicense {
  name: string
  url?: string
}

Source

Since v1.0.0

OpenAPISpecMethodName (type alias)

Signature

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

Source

Since v1.0.0

OpenAPISpecOperation (interface)

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 v1.0.0

OpenAPISpecParameter (interface)

Signature

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

Source

Since v1.0.0

OpenAPISpecPathItem (type alias)

Signature

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

Source

Since v1.0.0

OpenAPISpecPaths (type alias)

Signature

type OpenAPISpecPaths = Record<string, OpenAPISpecPathItem>

Source

Since v1.0.0

OpenAPISpecRequestBody (interface)

Signature

export interface OpenAPISpecRequestBody {
  content: OpenApiSpecContent
  required: true
}

Source

Since v1.0.0

OpenAPISpecResponses (type alias)

Signature

type OpenAPISpecResponses = Record<number, OpenApiSpecResponse>

Source

Since v1.0.0

OpenAPISpecServer (interface)

Signature

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

Source

Since v1.0.0

OpenAPISpecServerVariable (interface)

Signature

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

Source

Since v1.0.0

OpenAPISpecTag (interface)

Signature

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

Source

Since v1.0.0

OpenApiSpecContent (type alias)

Signature

type OpenApiSpecContent = {
  [K in OpenApiSpecContentType]?: OpenApiSpecMediaType
}

Source

Since v1.0.0

OpenApiSpecContentType (type alias)

Signature

type OpenApiSpecContentType =
  | "application/json"
  | "application/xml"
  | "application/x-www-form-urlencoded"
  | "multipart/form-data"
  | "text/plain"

Source

Since v1.0.0

OpenApiSpecMediaType (interface)

Signature

export interface OpenApiSpecMediaType {
  schema: JsonSchema.JsonSchema
}

Source

Since v1.0.0

OpenApiSpecResponse (interface)

Signature

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

Source

Since v1.0.0