@moostjs/swagger 0.5.33 → 0.6.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Mate, TMoostMetadata, TMateParamMeta } from 'moost';
-import { THeaderHook, TStatusHook } from '@wooksjs/event-http';
+import { THeaderHook, TStatusHook } from '@moostjs/event-http';
 
 type TFunction = Function;
 
@@ -7,10 +7,33 @@ interface TSwaggerOptions {
     title?: string;
     description?: string;
     version?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+    termsOfService?: string;
     cors?: boolean | string;
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+    tags?: {
+        name: string;
+        description?: string;
+        externalDocs?: TSwaggerExternalDocs;
+    }[];
+    externalDocs?: TSwaggerExternalDocs;
+    openapiVersion?: '3.0' | '3.1';
+    securitySchemes?: Record<string, TSwaggerSecurityScheme>;
+    security?: TSwaggerSecurityRequirement[];
 }
 interface TSwaggerSchema {
-    type?: string;
+    type?: string | string[];
     $ref?: string;
     title?: string;
     description?: string;
@@ -41,62 +64,306 @@ interface TSwaggerSchema {
     oneOf?: TSwaggerSchema[];
     not?: TSwaggerSchema;
     const?: unknown;
+    discriminator?: {
+        propertyName: string;
+        mapping?: Record<string, string>;
+    };
+    $defs?: Record<string, TSwaggerSchema>;
 }
 
+/** Returns the shared `Mate` instance extended with Swagger/OpenAPI metadata fields. */
 declare function getSwaggerMate(): Mate<TMoostMetadata & TSwaggerMate & {
-    params: Array<TMateParamMeta>;
+    params: TMateParamMeta[];
 }, TMoostMetadata & TSwaggerMate & {
-    params: Array<TMateParamMeta>;
+    params: TMateParamMeta[];
 }>;
+/** Swagger/OpenAPI metadata fields attached to classes and methods by swagger decorators. */
 interface TSwaggerMate {
     swaggerTags: string[];
     swaggerExclude: boolean;
     swaggerDescription: string;
-    swaggerResponses: Record<number, Record<string, {
-        response: TSwaggerConfigType;
-        example?: unknown;
-    }>>;
+    swaggerResponses: Record<number, {
+        description?: string;
+        headers?: Record<string, TSwaggerResponseHeader>;
+        content: Record<string, {
+            response: TSwaggerConfigType;
+            example?: unknown;
+        }>;
+    }>;
     swaggerRequestBody: Record<string, TSwaggerConfigType>;
     swaggerExample?: unknown;
-    swaggerParams: Array<{
+    swaggerParams: {
         name: string;
         in: 'query' | 'header' | 'path' | 'formData' | 'body';
         description?: string;
         required?: boolean;
         type?: TSwaggerConfigType;
-    }>;
+    }[];
+    swaggerLinks?: TSwaggerLinkConfig[];
+    swaggerCallbacks?: TSwaggerCallbackConfig[];
+    swaggerSecurity?: TSwaggerSecurityRequirement[];
+    swaggerPublic?: boolean;
+    swaggerDeprecated?: boolean;
+    swaggerOperationId?: string;
+    swaggerExternalDocs?: TSwaggerExternalDocs;
 }
+/** A type reference for OpenAPI schema generation — class, schema object, or array wrapper. */
 type TSwaggerConfigType = TFunction | {
     toJsonSchema?: () => unknown;
-} | TSwaggerSchema;
+} | TSwaggerSchema | [TSwaggerConfigType];
+/** Describes a single response header in the OpenAPI spec. */
+interface TSwaggerResponseHeader {
+    description?: string;
+    required?: boolean;
+    type?: TSwaggerConfigType;
+    example?: unknown;
+}
 interface TSwaggerResponseConfig {
     contentType?: string;
     description?: string;
     response: TSwaggerConfigType;
+    example?: unknown;
+    headers?: Record<string, TSwaggerResponseHeader>;
 }
+/** Options accepted by `@SwaggerResponse` — either a bare schema type or a full config. */
 type TSwaggerResponseOpts = TSwaggerConfigType | TSwaggerResponseConfig;
+/** External documentation link for an OpenAPI operation. */
+interface TSwaggerExternalDocs {
+    url: string;
+    description?: string;
+}
+/** Configuration for an OpenAPI 3.0 link object on a response. */
+interface TSwaggerLinkConfig {
+    /** Status code this link applies to. 0 = use default for the HTTP method. */
+    statusCode: number;
+    /** The link name (key in the response `links` object). */
+    name: string;
+    /** Target operation by explicit operationId string. */
+    operationId?: string;
+    /** Target operation by JSON pointer (operationRef). */
+    operationRef?: string;
+    /** Target operation by controller class + method name, resolved at mapping time. */
+    handler?: [TFunction, string];
+    /** Map of parameter name to runtime expression (e.g. `'$response.body#/id'`). */
+    parameters?: Record<string, string>;
+    /** Runtime expression for the request body. */
+    requestBody?: string;
+    /** Human-readable description. */
+    description?: string;
+    /** Alternative server for the link target. */
+    server?: {
+        url: string;
+        description?: string;
+    };
+}
+/** Configuration for an OpenAPI 3.0 callback (webhook) on an operation. */
+interface TSwaggerCallbackConfig {
+    /** Callback name (key in the operation's `callbacks` object). */
+    name: string;
+    /** Runtime expression for the callback URL (e.g. `'{$request.body#/callbackUrl}'`). */
+    expression: string;
+    /** HTTP method your server uses to call the webhook (default: `'post'`). */
+    method?: string;
+    /** Schema for the request body your server sends. Resolved via the schema pipeline. */
+    requestBody?: TSwaggerConfigType;
+    /** Content type for the request body (default: `'application/json'`). */
+    contentType?: string;
+    /** Description for the callback operation. */
+    description?: string;
+    /** Expected response status code from the webhook receiver (default: `200`). */
+    responseStatus?: number;
+    /** Description for the expected response (default: `'OK'`). */
+    responseDescription?: string;
+}
+/** OpenAPI security requirement — maps scheme name to required scopes. */
+type TSwaggerSecurityRequirement = Record<string, string[]>;
+/** OpenAPI HTTP security scheme (e.g. bearer, basic). */
+interface TSwaggerSecuritySchemeHttp {
+    type: 'http';
+    scheme: string;
+    bearerFormat?: string;
+    description?: string;
+}
+/** OpenAPI API key security scheme. */
+interface TSwaggerSecuritySchemeApiKey {
+    type: 'apiKey';
+    in: 'header' | 'query' | 'cookie';
+    name: string;
+    description?: string;
+}
+/** Configuration for a single OAuth2 flow. */
+interface TSwaggerSecuritySchemeOAuth2Flow {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+}
+/** OpenAPI OAuth2 security scheme with one or more flows. */
+interface TSwaggerSecuritySchemeOAuth2 {
+    type: 'oauth2';
+    flows: {
+        implicit?: TSwaggerSecuritySchemeOAuth2Flow;
+        password?: TSwaggerSecuritySchemeOAuth2Flow;
+        clientCredentials?: TSwaggerSecuritySchemeOAuth2Flow;
+        authorizationCode?: TSwaggerSecuritySchemeOAuth2Flow;
+    };
+    description?: string;
+}
+/** OpenAPI OpenID Connect security scheme. */
+interface TSwaggerSecuritySchemeOpenIdConnect {
+    type: 'openIdConnect';
+    openIdConnectUrl: string;
+    description?: string;
+}
+/** Union of all supported OpenAPI security scheme types. */
+type TSwaggerSecurityScheme = TSwaggerSecuritySchemeHttp | TSwaggerSecuritySchemeApiKey | TSwaggerSecuritySchemeOAuth2 | TSwaggerSecuritySchemeOpenIdConnect;
 
+/** Adds an OpenAPI tag to a controller or handler for grouping in the Swagger UI. */
 declare const SwaggerTag: (tag: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Excludes a controller or handler from the generated OpenAPI spec. */
 declare const SwaggerExclude: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Sets the OpenAPI description for a handler. */
 declare const SwaggerDescription: (descr: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
-declare function SwaggerResponse(opts: TSwaggerResponseOpts, exmaple?: unknown): MethodDecorator;
-declare function SwaggerResponse(code: number, opts: TSwaggerResponseOpts, exmaple?: unknown): MethodDecorator;
+/**
+ * Defines a response schema in the OpenAPI spec.
+ * Can be called with just options (uses status 200) or with an explicit status code.
+ *
+ * @example
+ * ```ts
+ * @SwaggerResponse({ response: MyDto })
+ * @SwaggerResponse(404, { response: ErrorDto })
+ * ```
+ */
+declare function SwaggerResponse(opts: TSwaggerResponseOpts, example?: unknown): MethodDecorator;
+declare function SwaggerResponse(code: number, opts: TSwaggerResponseOpts, example?: unknown): MethodDecorator;
+/**
+ * Defines the request body schema in the OpenAPI spec.
+ *
+ * @param opt - Schema definition. Use `{ response: MyDto }` for a typed schema,
+ *   or `{ response: MyDto, contentType: 'multipart/form-data' }` for a specific content type.
+ */
 declare function SwaggerRequestBody(opt: TSwaggerResponseOpts): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Defines a parameter (query, path, header, cookie) in the OpenAPI spec. */
 declare function SwaggerParam(opts: TSwaggerMate['swaggerParams'][number]): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Attaches an example value to a handler's OpenAPI documentation. */
 declare function SwaggerExample(example: unknown): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Marks a handler or controller as public, opting out of inherited security requirements. */
+declare const SwaggerPublic: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Marks a handler or controller as deprecated in the OpenAPI spec. */
+declare const SwaggerDeprecated: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Overrides the auto-generated operationId for an endpoint. */
+declare const SwaggerOperationId: (id: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Links an operation to external documentation. */
+declare const SwaggerExternalDocs: (url: string, description?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * Attaches a security requirement to a handler or controller (OR semantics).
+ * Multiple calls add alternative requirements — any one suffices.
+ *
+ * @param schemeName - The name of the security scheme (must match a key in securitySchemes)
+ * @param scopes - OAuth2/OIDC scopes required (default: [])
+ */
+declare function SwaggerSecurity(schemeName: string, scopes?: string[]): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * Attaches a combined security requirement (AND semantics).
+ * All schemes in the requirement must be satisfied simultaneously.
+ */
+declare function SwaggerSecurityAll(requirement: TSwaggerSecurityRequirement): MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/** Options for the `@SwaggerLink` decorator — identifies the target operation and parameter mapping. */
+interface TSwaggerLinkOptions {
+    /** Target by explicit operationId string. */
+    operationId?: string;
+    /** Target by JSON pointer (operationRef). */
+    operationRef?: string;
+    /** Target by controller class + method name, resolved at mapping time. */
+    handler?: [TFunction, string];
+    /** Map of parameter name to runtime expression (e.g. `'$response.body#/id'`). */
+    parameters?: Record<string, string>;
+    /** Runtime expression for the request body. */
+    requestBody?: string;
+    /** Human-readable description. */
+    description?: string;
+    /** Alternative server for the link target. */
+    server?: {
+        url: string;
+        description?: string;
+    };
+}
+/**
+ * Adds an OpenAPI link to a response, describing how response values
+ * can be used as input to another operation.
+ *
+ * @example
+ * ```ts
+ * // Reference by operationId
+ * @SwaggerLink('GetUser', {
+ *   operationId: 'getUser',
+ *   parameters: { userId: '$response.body#/id' },
+ * })
+ *
+ * // Reference by controller class + method (resolved at mapping time)
+ * @SwaggerLink('GetUser', {
+ *   handler: [UserController, 'getUser'],
+ *   parameters: { userId: '$response.body#/id' },
+ * })
+ *
+ * // On a specific status code
+ * @SwaggerLink(201, 'GetUser', {
+ *   operationId: 'getUser',
+ *   parameters: { userId: '$response.body#/id' },
+ * })
+ * ```
+ */
+declare function SwaggerLink(name: string, options: TSwaggerLinkOptions): MethodDecorator;
+declare function SwaggerLink(statusCode: number, name: string, options: TSwaggerLinkOptions): MethodDecorator;
+/** Options for the `@SwaggerCallback` decorator — describes a webhook your server sends. */
+interface TSwaggerCallbackOptions {
+    /** Runtime expression for the callback URL (e.g. `'{$request.body#/callbackUrl}'`). */
+    expression: string;
+    /** HTTP method your server uses to call the webhook (default: `'post'`). */
+    method?: string;
+    /** Schema for the request body your server sends. Resolved via the schema pipeline. */
+    requestBody?: TSwaggerConfigType;
+    /** Content type for the request body (default: `'application/json'`). */
+    contentType?: string;
+    /** Description for the callback operation. */
+    description?: string;
+    /** Expected response status code from the webhook receiver (default: `200`). */
+    responseStatus?: number;
+    /** Description for the expected response (default: `'OK'`). */
+    responseDescription?: string;
+}
+/**
+ * Documents an OpenAPI callback (webhook) on an operation.
+ * Describes a request your server sends to a client-provided URL.
+ *
+ * @example
+ * ```ts
+ * @SwaggerCallback('onEvent', {
+ *   expression: '{$request.body#/callbackUrl}',
+ *   requestBody: EventPayloadDto,
+ *   description: 'Event notification sent to subscriber',
+ * })
+ * @Post('subscribe')
+ * subscribe() { ... }
+ * ```
+ */
+declare function SwaggerCallback(name: string, options: TSwaggerCallbackOptions): MethodDecorator;
 
+/** Serves the Swagger UI, spec.json, and spec.yaml under the `/api-docs` route prefix. */
 declare class SwaggerController {
     protected opts: TSwaggerOptions;
     constructor(opts?: TSwaggerOptions);
     'assetPath': string;
-    protected 'processCors'(): void;
-    'serveIndex'(url: string, location: THeaderHook, status: TStatusHook): string;
+    protected processCors(): void;
+    serveIndex(url: string, location: THeaderHook, status: TStatusHook): string;
     'swagger-initializer.js'(): string;
     'spec'?: Record<string, unknown>;
+    protected resolveSpec(): Promise<Record<string, unknown>>;
     'spec.json'(): Promise<Record<string, unknown>>;
-    'files'(url: string): Promise<unknown>;
-    'serve'(path: string): Promise<unknown>;
+    'spec.yaml'(): Promise<string>;
+    files(url: string): Promise<unknown>;
+    serve(path: string): Promise<unknown>;
 }
 
-export { SwaggerController, SwaggerDescription, SwaggerExample, SwaggerExclude, SwaggerParam, SwaggerRequestBody, SwaggerResponse, SwaggerTag, getSwaggerMate };
-export type { TSwaggerConfigType, TSwaggerMate, TSwaggerResponseOpts };
+export { SwaggerCallback, SwaggerController, SwaggerDeprecated, SwaggerDescription, SwaggerExample, SwaggerExclude, SwaggerExternalDocs, SwaggerLink, SwaggerOperationId, SwaggerParam, SwaggerPublic, SwaggerRequestBody, SwaggerResponse, SwaggerSecurity, SwaggerSecurityAll, SwaggerTag, getSwaggerMate };
+export type { TSwaggerCallbackConfig, TSwaggerCallbackOptions, TSwaggerConfigType, TSwaggerExternalDocs, TSwaggerLinkConfig, TSwaggerLinkOptions, TSwaggerMate, TSwaggerResponseHeader, TSwaggerResponseOpts, TSwaggerSecurityRequirement, TSwaggerSecurityScheme, TSwaggerSecuritySchemeApiKey, TSwaggerSecuritySchemeHttp, TSwaggerSecuritySchemeOAuth2, TSwaggerSecuritySchemeOAuth2Flow, TSwaggerSecuritySchemeOpenIdConnect };