OpenApi

39 exports Since v1.0.0 Source

Annotations

annotations

Since v1.0.0

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>

Deprecated

Since v1.0.0

Signature

declare class Deprecated extends any {
  constructor();
}

Description

Since v1.0.0

Signature

declare class Description extends any {
  constructor();
}

Exclude

Since v1.0.0

Signature

declare class Exclude extends any {
  constructor();
}

ExternalDocs

Since v1.0.0

Signature

declare class ExternalDocs extends any {
  constructor();
}

Format

Since v1.0.0

Signature

declare class Format extends any {
  constructor();
}

Identifier

Since v1.0.0

Signature

declare class Identifier extends any {
  constructor();
}

License

Since v1.0.0

Signature

declare class License extends any {
  constructor();
}

Override

Since v1.0.0

Signature

declare class Override extends any {
  constructor();
}

Servers

Since v1.0.0

Signature

declare class Servers extends any {
  constructor();
}

Summary

Since v1.0.0

Signature

declare class Summary extends any {
  constructor();
}

Title

Since v1.0.0

Signature

declare class Title extends any {
  constructor();
}

Transform

Since v1.0.0

Transforms the generated OpenAPI specification

Signature

declare class Transform extends any {
  constructor();
}

Version

Since v1.0.0

Signature

declare class Version extends any {
  constructor();
}

Constructors

fromApi

Since v1.0.0

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.

Signature

declare function fromApi<Id extends string, Groups extends Any, E, R>(api: HttpApi<Id, Groups, E, R>, options?: {
  readonly additionalPropertiesStrategy?: AdditionalPropertiesStrategy;
}): OpenAPISpec

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

type OpenAPISecurityScheme = OpenAPIHTTPSecurityScheme | OpenAPIApiKeySecurityScheme

OpenAPISpec

interface

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

Since v1.0.0

Signature

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

OpenApiSpecContentType

type

Since v1.0.0

Signature

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

OpenAPISpecExternalDocs

interface

Since v1.0.0

Signature

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

OpenAPISpecInfo

interface

Since v1.0.0

Signature

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

OpenAPISpecLicense

interface

Since v1.0.0

Signature

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

OpenApiSpecMediaType

interface

Since v1.0.0

Signature

interface OpenApiSpecMediaType {
  schema: JsonSchema;
}

OpenAPISpecMethodName

type

Since v1.0.0

Signature

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

OpenAPISpecOperation

interface

Since v1.0.0

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

Since v1.0.0

Signature

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

OpenAPISpecPathItem

type

Since v1.0.0

Signature

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

OpenAPISpecPaths

type

Since v1.0.0

Signature

type OpenAPISpecPaths = Record<string, OpenAPISpecPathItem>

OpenAPISpecRequestBody

interface

Since v1.0.0

Signature

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

OpenApiSpecResponse

interface

Since v1.0.0

Signature

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

OpenAPISpecResponses

type

Since v1.0.0

Signature

type OpenAPISpecResponses = Record<number, OpenApiSpecResponse>

OpenAPISpecServer

interface

Since v1.0.0

Signature

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

OpenAPISpecServerVariable

interface

Since v1.0.0

Signature

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

OpenAPISpecTag

interface

Since v1.0.0

Signature

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