alepha/dist/server/swagger/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import "alepha/security";
import { Alepha, KIND, Primitive, Static, TObject } from "alepha";
import { ActionPrimitive, RequestConfigSchema, ServerProvider, ServerRouterProvider } from "alepha/server";
import { ServerStaticProvider } from "alepha/server/static";
import { FileSystemProvider } from "alepha/system";
//#region ../../src/server/swagger/primitives/$swagger.d.ts
/**
 * Creates an OpenAPI/Swagger documentation primitive with interactive UI.
 *
 * Automatically generates API documentation from your $action primitives and serves
 * an interactive Swagger UI for testing endpoints. Supports customization, tag filtering,
 * and OAuth configuration.
 *
 * @example
 * ```ts
 * class App {
 *   docs = $swagger({
 *     prefix: "/api-docs",
 *     info: {
 *       title: "My API",
 *       version: "1.0.0",
 *       description: "REST API documentation"
 *     },
 *     excludeTags: ["internal"],
 *     ui: { root: "/swagger" }
 *   });
 * }
 * ```
 */
declare const $swagger: {
  (options?: SwaggerPrimitiveOptions): SwaggerPrimitive;
  [KIND]: typeof SwaggerPrimitive;
};
interface SwaggerPrimitiveOptions {
  info?: OpenApiDocument["info"];
  /**
   * @default: "/docs"
   */
  prefix?: string;
  /**
   * If true, docs will be disabled.
   */
  disabled?: boolean;
  /**
   * Tags to exclude from the documentation.
   */
  excludeTags?: string[];
  /**
   * Server URLs for the API.
   * If not provided, the server hostname is used automatically.
   */
  servers?: OpenApiServer[];
  /**
   * Enable Swagger UI.
   *
   * @default true
   */
  ui?: boolean | SwaggerUiOptions;
  /**
   * Function to rewrite the OpenAPI document before serving it.
   */
  rewrite?: (doc: OpenApiDocument) => void;
}
interface OpenApiServer {
  url: string;
  description?: string;
}
interface SwaggerUiOptions {
  root?: string;
  /**
   * If true, the authorization data is persisted in browser localStorage.
   *
   * @default true
   */
  persistAuthorization?: boolean;
  initOAuth?: {
    /**
     * Default clientId.
     */
    clientId?: string;
    /**
     * realm query parameter (for oauth1) added to authorizationUrl and tokenUrl.
     */
    realm?: string;
    /**
     * application name, displayed in authorization popup.
     */
    appName?: string;
    /**
     * scope separator for passing scopes, encoded before calling, default
     * value is a space (encoded value %20).
     *
     * @default ' '
     */
    scopeSeparator?: string;
    /**
     * string array or scope separator (i.e. space) separated string of
     * initially selected oauth scopes
     *
     * @default []
     */
    scopes?: string | string[];
    /**
     * Additional query parameters added to authorizationUrl and tokenUrl.
     * MUST be an object
     */
    additionalQueryStringParams?: {
      [key: string]: any;
    };
    /**
     * Only activated for the accessCode flow. During the authorization_code
     * request to the tokenUrl, pass the Client Password using the HTTP Basic
     * Authentication scheme (Authorization header with Basic
     * base64encode(client_id + client_secret)).
     *
     * @default false
     */
    useBasicAuthenticationWithAccessCodeGrant?: boolean;
    /**
     * Only applies to Authorization Code flows. Proof Key for Code Exchange
     * brings enhanced security for OAuth public clients.
     *
     * @default false
     */
    usePkceWithAuthorizationCodeGrant?: boolean;
  };
}
declare class SwaggerPrimitive extends Primitive<SwaggerPrimitiveOptions> {}
interface OpenApiDocument {
  openapi: string;
  info: {
    title: string;
    version: string;
    description?: string;
  };
  servers?: OpenApiServer[];
  paths: Record<string, any>;
  components?: {
    schemas?: Record<string, any>;
    securitySchemes?: Record<string, any>;
  };
}
interface OpenApiOperation {
  tags?: string[];
  summary?: string;
  description?: string;
  operationId?: string;
  deprecated?: boolean;
  parameters?: Array<{
    name: string;
    in: "query" | "header" | "path" | "cookie";
    description?: string;
    required?: boolean;
    schema: any;
  }>;
  requestBody?: {
    description?: string;
    content: Record<string, {
      schema: any;
    }>;
    required?: boolean;
  };
  responses: Record<string, {
    description: string;
    content?: Record<string, {
      schema: any;
    }>;
  }>;
  security?: Array<Record<string, any[]>>;
}
//#endregion
//#region ../../src/server/swagger/providers/ServerSwaggerProvider.d.ts
/**
 * Swagger provider configuration atom
 */
declare const swaggerOptions: import("alepha").Atom<import("zod").ZodObject<{
  excludeKeys: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
}, import("zod/v4/core").$strip>, "alepha.server.swagger.options">;
type ServerSwaggerProviderOptions = Static<typeof swaggerOptions.schema>;
declare module "alepha" {
  interface State {
    [swaggerOptions.key]: ServerSwaggerProviderOptions;
  }
}
declare class ServerSwaggerProvider {
  protected readonly serverStaticProvider: ServerStaticProvider;
  protected readonly serverRouterProvider: ServerRouterProvider;
  protected readonly serverProvider: ServerProvider;
  protected readonly alepha: Alepha;
  protected readonly log: import("alepha/logger").Logger;
  protected readonly options: Readonly<{
    excludeKeys?: string[] | undefined;
  }>;
  protected readonly fs: FileSystemProvider;
  json?: OpenApiDocument;
  protected readonly configure: import("alepha").HookPrimitive<"configure">;
  generateSwaggerDoc(options: SwaggerPrimitiveOptions): OpenApiDocument;
  protected setupSwaggerPlugin(options: SwaggerPrimitiveOptions): Promise<OpenApiDocument | undefined>;
  protected configureOpenApi(actions: ActionPrimitive<RequestConfigSchema>[], doc: SwaggerPrimitiveOptions): OpenApiDocument;
  isBodyMultipart(schema: TObject): boolean;
  replacePathParams(url: string): string;
  getResponseSchema(route: ActionPrimitive<RequestConfigSchema>): {
    type?: string;
    schema?: any;
    status: number;
  } | undefined;
  protected extractExample(schema: any): any;
  protected getStatusDescription(status: number): string;
  protected getContentType(schema: any): string | undefined;
  protected configureSwaggerApi(prefix: string, json: OpenApiDocument): void;
  protected configureSwaggerUi(prefix: string, options: SwaggerPrimitiveOptions): Promise<void>;
  protected getAssetPath(...paths: (string | undefined)[]): Promise<string | undefined>;
  removePrivateFields<T extends Record<string, any>>(obj: T, excludeList: string[]): T;
}
//#endregion
//#region ../../src/server/swagger/index.d.ts
declare module "alepha/server" {
  interface ActionPrimitiveOptions<TConfig extends RequestConfigSchema> {
    /**
     * Short description of the route.
     */
    summary?: string;
    /**
     * Don't include this action in the Swagger documentation.
     */
    hide?: boolean;
    /**
     * Mark this action as deprecated in the documentation.
     */
    deprecated?: boolean;
  }
}
/**
 * Automatic API documentation generation.
 *
 * **Features:**
 * - Swagger/OpenAPI configuration
 * - Routes: `GET /swagger/ui`, `GET /swagger.json`
 *
 * @module alepha.server.swagger
 */
declare const AlephaServerSwagger: import("alepha").Service<import("alepha").Module>;
//#endregion
export { $swagger, AlephaServerSwagger, OpenApiDocument, OpenApiOperation, OpenApiServer, ServerSwaggerProvider, ServerSwaggerProviderOptions, SwaggerPrimitive, SwaggerPrimitiveOptions, SwaggerUiOptions, swaggerOptions };
//# sourceMappingURL=index.d.ts.map