express-zod-api/dist/documentation.d.ts

A Typescript framework to help you get an API server up and running with I/O schema validation and custom middlewares in minutes.

import { M as ResponseVariant, g as CommonConfig, t as Routing } from "./routing-xQnwfH2D.js";
import {
  a as depictTags,
  n as Depicter,
  o as trimSummary,
  r as IsHeader,
  t as BrandHandling,
} from "./documentation-helpers-C3vkQCz2.js";
import { InfoObject, OpenApiBuilder, ServerObject } from "openapi3-ts/oas32";
type Component = `${ResponseVariant}Response` | "requestParameter" | "requestBody";
/** @desc user defined function that creates a component description from its properties */
type Descriptor = (
  props: Record<"method" | "path" | "operationId", string> & {
    statusCode?: number;
  },
) => string;
type Summarizer = (params: { summary?: string; description?: string; trim: typeof trimSummary }) => string | undefined;
interface DocumentationParams {
  /**
   * @desc The metadata about the API
   * @default { title: "Generated by Express Zod API", version: "0.0.0" }
   * */
  info?: InfoObject;
  /**
   * @desc Server URL(s) or their complete definitions
   * @default []
   * */
  server?: string | ServerObject | Array<string | ServerObject>;
  routing: Routing;
  config: CommonConfig;
  /**
   * @desc Descriptions of various components based on their properties (method, path, operationId).
   * @desc When composition set to "components", component name is generated from this description
   * @default () => `${method} ${path} ${component}`
   * */
  descriptions?: Partial<Record<Component, Descriptor>>;
  /**
   * @desc The function that ensures the maximum length for summary fields. Can optionally make them from descriptions.
   * @see defaultSummarizer
   * @see trimSummary
   * */
  summarizer?: Summarizer;
  /**
   * @desc Depict the HEAD method for each Endpoint supporting the GET method (feature of Express)
   * @default true
   * */
  hasHeadMethod?: boolean;
  /** @default inline */
  composition?: "inline" | "components";
  /**
   * @desc Handling rules for your own schemas branded with `x-brand` metadata.
   * @desc Keys: brands (recommended to use unique symbols).
   * @desc Values: functions having Zod context as first argument, second one is the framework context.
   * @example { MyBrand: ({ zodSchema, jsonSchema }) => ({ type: "object" })
   * @link https://www.npmjs.com/package/@express-zod-api/zod-plugin
   */
  brandHandling?: BrandHandling;
  /**
   * @desc Ability to configure recognition of headers among other input data
   * @desc Only applicable when "headers" is present within inputSources config option
   * @see defaultIsHeader
   * @link https://www.iana.org/assignments/http-fields/http-fields.xhtml
   * */
  isHeader?: IsHeader;
  /**
   * @desc Extended description of tags used in endpoints. For enforcing constraints:
   * @see TagOverrides
   * @example { users: "About users", files: { description: "About files", url: "https://example.com" } }
   * */
  tags?: Parameters<typeof depictTags>[0];
}
declare class Documentation extends OpenApiBuilder {
  constructor({ hasHeadMethod, ...rest }: DocumentationParams);
}
export { type Depicter, Documentation };