@riktajs/swagger 0.10.2 → 0.10.3

package/dist/index.d.cts

@@ -0,0 +1,498 @@
+export { CONTROLLER_METADATA, GUARDS_METADATA, HTTP_CODE_METADATA, PARAM_METADATA, ROUTES_METADATA, ZOD_SCHEMA_METADATA } from '@riktajs/core';
+import { ZodType } from 'zod';
+import { FastifyPluginAsync, FastifyInstance } from 'fastify';
+import { FastifySwaggerUiOptions } from '@fastify/swagger-ui';
+
+declare const API_TAGS_METADATA: unique symbol;
+declare const API_OPERATION_METADATA: unique symbol;
+declare const API_RESPONSE_METADATA: unique symbol;
+declare const API_PROPERTY_METADATA: unique symbol;
+declare const API_BODY_METADATA: unique symbol;
+declare const API_PARAM_METADATA: unique symbol;
+declare const API_QUERY_METADATA: unique symbol;
+declare const API_HEADER_METADATA: unique symbol;
+declare const API_SECURITY_METADATA: unique symbol;
+declare const API_EXCLUDE_METADATA: unique symbol;
+declare const API_DEPRECATED_METADATA: unique symbol;
+
+type OpenApiDataType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+type OpenApiFormat = 'int32' | 'int64' | 'float' | 'double' | 'date' | 'date-time' | 'password' | 'byte' | 'binary' | 'email' | 'uuid' | 'uri' | 'hostname' | 'ipv4' | 'ipv6';
+interface OpenApiSchemaObject {
+    type?: OpenApiDataType;
+    format?: string;
+    description?: string;
+    default?: unknown;
+    example?: unknown;
+    enum?: unknown[];
+    items?: OpenApiSchemaObject;
+    properties?: Record<string, OpenApiSchemaObject>;
+    required?: string[];
+    nullable?: boolean;
+    allOf?: OpenApiSchemaObject[];
+    oneOf?: OpenApiSchemaObject[];
+    anyOf?: OpenApiSchemaObject[];
+    not?: OpenApiSchemaObject;
+    $ref?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    additionalProperties?: boolean | OpenApiSchemaObject;
+}
+type ParameterLocation = 'query' | 'path' | 'header' | 'cookie';
+interface OpenApiParameterObject {
+    name: string;
+    in: ParameterLocation;
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: OpenApiSchemaObject;
+    example?: unknown;
+    examples?: Record<string, {
+        value: unknown;
+        summary?: string;
+    }>;
+}
+interface OpenApiRequestBodyObject {
+    description?: string;
+    required?: boolean;
+    content: Record<string, {
+        schema?: OpenApiSchemaObject;
+        example?: unknown;
+        examples?: Record<string, {
+            value: unknown;
+            summary?: string;
+        }>;
+    }>;
+}
+interface OpenApiResponseObject {
+    description: string;
+    content?: Record<string, {
+        schema?: OpenApiSchemaObject;
+        example?: unknown;
+    }>;
+    headers?: Record<string, {
+        description?: string;
+        schema?: OpenApiSchemaObject;
+    }>;
+}
+type OpenApiSecurityRequirement = Record<string, string[]>;
+interface OpenApiSecurityScheme {
+    type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+    description?: string;
+    name?: string;
+    in?: 'query' | 'header' | 'cookie';
+    scheme?: string;
+    bearerFormat?: string;
+    flows?: {
+        implicit?: {
+            authorizationUrl: string;
+            scopes: Record<string, string>;
+        };
+        password?: {
+            tokenUrl: string;
+            scopes: Record<string, string>;
+        };
+        clientCredentials?: {
+            tokenUrl: string;
+            scopes: Record<string, string>;
+        };
+        authorizationCode?: {
+            authorizationUrl: string;
+            tokenUrl: string;
+            scopes: Record<string, string>;
+        };
+    };
+    openIdConnectUrl?: string;
+}
+interface OpenApiOperation {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: {
+        url: string;
+        description?: string;
+    };
+    operationId?: string;
+    parameters?: Array<{
+        name: string;
+        in: 'path' | 'query' | 'header' | 'cookie';
+        description?: string;
+        required?: boolean;
+        deprecated?: boolean;
+        schema?: OpenApiSchemaObject;
+        example?: unknown;
+    }>;
+    requestBody?: {
+        description?: string;
+        required?: boolean;
+        content: Record<string, {
+            schema?: OpenApiSchemaObject;
+            example?: unknown;
+        }>;
+    };
+    responses: Record<string, {
+        description: string;
+        headers?: Record<string, {
+            description?: string;
+            schema?: OpenApiSchemaObject;
+        }>;
+        content?: Record<string, {
+            schema?: OpenApiSchemaObject;
+            example?: unknown;
+        }>;
+    }>;
+    deprecated?: boolean;
+    security?: Array<Record<string, string[]>>;
+}
+interface OpenApiPathItem {
+    get?: OpenApiOperation;
+    put?: OpenApiOperation;
+    post?: OpenApiOperation;
+    delete?: OpenApiOperation;
+    options?: OpenApiOperation;
+    head?: OpenApiOperation;
+    patch?: OpenApiOperation;
+    trace?: OpenApiOperation;
+    summary?: string;
+    description?: string;
+    parameters?: Array<{
+        name: string;
+        in: 'path' | 'query' | 'header' | 'cookie';
+        required?: boolean;
+        schema?: OpenApiSchemaObject;
+    }>;
+}
+interface OpenApiInfoObject {
+    title: string;
+    version: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+        identifier?: string;
+    };
+}
+interface OpenApiDocument {
+    openapi: string;
+    info: OpenApiInfoObject;
+    paths: Record<string, OpenApiPathItem>;
+    servers?: Array<{
+        url: string;
+        description?: string;
+        variables?: Record<string, {
+            default: string;
+            description?: string;
+            enum?: string[];
+        }>;
+    }>;
+    components?: {
+        schemas?: Record<string, OpenApiSchemaObject>;
+        securitySchemes?: Record<string, OpenApiSecurityScheme | {
+            type: string;
+            description?: string;
+            name?: string;
+            in?: string;
+            scheme?: string;
+            bearerFormat?: string;
+            flows?: unknown;
+        }>;
+        responses?: Record<string, OpenApiResponseObject>;
+        parameters?: Record<string, OpenApiParameterObject>;
+        requestBodies?: Record<string, OpenApiRequestBodyObject>;
+    };
+    security?: Array<Record<string, string[]>>;
+    tags?: Array<{
+        name: string;
+        description?: string;
+        externalDocs?: {
+            url: string;
+            description?: string;
+        };
+    }>;
+    externalDocs?: {
+        url: string;
+        description?: string;
+    };
+}
+interface ApiOperationOptions {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    deprecated?: boolean;
+    tags?: string[];
+}
+interface ApiResponseOptions {
+    status: number;
+    description?: string;
+    schema?: ZodType<unknown> | OpenApiSchemaObject;
+    type?: string;
+    example?: unknown;
+    isArray?: boolean;
+}
+interface ApiPropertyOptions {
+    description?: string;
+    example?: unknown;
+    default?: unknown;
+    required?: boolean;
+    type?: OpenApiDataType | string;
+    format?: OpenApiFormat | string;
+    enum?: unknown[];
+    nullable?: boolean;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    deprecated?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+}
+interface ApiParamOptions {
+    name: string;
+    description?: string;
+    required?: boolean;
+    type?: OpenApiDataType | string;
+    format?: OpenApiFormat | string;
+    example?: unknown;
+    enum?: unknown[];
+    deprecated?: boolean;
+    schema?: ZodType<unknown>;
+}
+interface ApiQueryOptions extends Omit<ApiParamOptions, 'required'> {
+    required?: boolean;
+    isArray?: boolean;
+}
+interface ApiHeaderOptions {
+    name: string;
+    description?: string;
+    required?: boolean;
+    type?: OpenApiDataType | string;
+    deprecated?: boolean;
+    example?: unknown;
+    schema?: ZodType<unknown>;
+}
+interface ApiBodyOptions {
+    description?: string;
+    required?: boolean;
+    type?: string;
+    schema?: ZodType<unknown> | OpenApiSchemaObject;
+    example?: unknown;
+    examples?: Record<string, {
+        value: unknown;
+        summary?: string;
+        description?: string;
+    }>;
+    isArray?: boolean;
+}
+interface ApiSecurityOptions {
+    name: string;
+    scopes?: string[];
+}
+interface SwaggerServerConfig {
+    url: string;
+    description?: string;
+    variables?: Record<string, {
+        default: string;
+        description?: string;
+        enum?: string[];
+    }>;
+}
+interface SwaggerContactConfig {
+    name?: string;
+    url?: string;
+    email?: string;
+}
+interface SwaggerLicenseConfig {
+    name: string;
+    url?: string;
+    identifier?: string;
+}
+interface SwaggerExternalDocsConfig {
+    url: string;
+    description?: string;
+}
+interface SwaggerTagConfig {
+    name: string;
+    description?: string;
+    externalDocs?: SwaggerExternalDocsConfig;
+}
+interface SwaggerConfig {
+    info?: OpenApiInfoObject;
+    externalDocs?: SwaggerExternalDocsConfig;
+    servers?: SwaggerServerConfig[];
+    tags?: SwaggerTagConfig[];
+    securitySchemes?: Record<string, OpenApiSecurityScheme>;
+    security?: OpenApiSecurityRequirement[];
+    jsonPath?: string;
+    uiPath?: string;
+    openApiVersion?: '3.0.0' | '3.0.1' | '3.0.2' | '3.0.3' | '3.1.0';
+    includeUndocumented?: boolean;
+    basePath?: string;
+}
+interface StoredResponseMetadata extends ApiResponseOptions {
+    _stored: true;
+}
+interface StoredParamMetadata extends ApiParamOptions {
+    _stored: true;
+    location: ParameterLocation;
+}
+interface ExtractedRouteInfo {
+    method: string;
+    path: string;
+    handlerName: string | symbol;
+    controllerPrefix: string;
+    controllerClass: Function;
+}
+type Constructor$2<T = unknown> = new (...args: any[]) => T;
+
+declare function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator;
+declare function getApiTags(target: Function, propertyKey?: string | symbol): string[];
+
+declare function ApiOperation(options: ApiOperationOptions): MethodDecorator;
+declare function getApiOperation(target: Function, propertyKey: string | symbol): ApiOperationOptions | undefined;
+
+declare function ApiResponse(options: ApiResponseOptions): MethodDecorator;
+declare function ApiOkResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiCreatedResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiAcceptedResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiNoContentResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiBadRequestResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiUnauthorizedResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiForbiddenResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiNotFoundResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiConflictResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiUnprocessableEntityResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function ApiInternalServerErrorResponse(options?: Omit<ApiResponseOptions, 'status'>): MethodDecorator;
+declare function getApiResponses(target: Function, propertyKey: string | symbol): ApiResponseOptions[];
+
+declare function ApiBody(options: ApiBodyOptions): MethodDecorator;
+declare function getApiBody(target: Function, propertyKey: string | symbol): ApiBodyOptions | undefined;
+
+declare function ApiParam(options: ApiParamOptions): MethodDecorator;
+declare function getApiParams(target: Function, propertyKey: string | symbol): ApiParamOptions[];
+
+declare function ApiQuery(options: ApiQueryOptions): MethodDecorator;
+declare function getApiQueries(target: Function, propertyKey: string | symbol): ApiQueryOptions[];
+
+declare function ApiHeader(options: ApiHeaderOptions): MethodDecorator;
+declare function getApiHeaders(target: Function, propertyKey: string | symbol): ApiHeaderOptions[];
+
+declare function ApiSecurity(name?: string, scopes?: string[]): ClassDecorator & MethodDecorator;
+declare function ApiBearerAuth(name?: string): ClassDecorator & MethodDecorator;
+declare function ApiBasicAuth(name?: string): ClassDecorator & MethodDecorator;
+declare function ApiOAuth2(scopes?: string[], name?: string): ClassDecorator & MethodDecorator;
+declare function ApiCookieAuth(name?: string): ClassDecorator & MethodDecorator;
+declare function getApiSecurity(target: Function, propertyKey?: string | symbol): ApiSecurityOptions | null | undefined;
+
+interface StoredPropertyMetadata {
+    propertyKey: string | symbol;
+    options: ApiPropertyOptions;
+}
+declare function ApiProperty(options?: ApiPropertyOptions): PropertyDecorator;
+declare function ApiPropertyOptional(options?: Omit<ApiPropertyOptions, 'required'>): PropertyDecorator;
+declare function ApiHideProperty(): PropertyDecorator;
+declare function getApiProperties(target: Function): StoredPropertyMetadata[];
+
+declare function ApiExcludeEndpoint(): MethodDecorator;
+declare function ApiExcludeController(): ClassDecorator;
+declare function isApiExcluded(target: Function, propertyKey?: string | symbol): boolean;
+declare function ApiDeprecated(message?: string): MethodDecorator;
+declare function getApiDeprecated(target: Function, propertyKey: string | symbol): {
+    deprecated: boolean;
+    message?: string;
+} | undefined;
+
+type Constructor$1<T = unknown> = new (...args: any[]) => T;
+interface OpenApiGeneratorConfig extends Omit<SwaggerConfig, 'info'> {
+    title?: string;
+    version?: string;
+    description?: string;
+    contact?: OpenApiInfoObject['contact'];
+    license?: OpenApiInfoObject['license'];
+    termsOfService?: string;
+    info?: OpenApiInfoObject;
+}
+declare class OpenApiGenerator {
+    private config;
+    private controllers;
+    private globalSecuritySchemes;
+    constructor(config?: OpenApiGeneratorConfig);
+    addController(controller: Constructor$1): this;
+    addControllers(controllers: Constructor$1[]): this;
+    addSecurityScheme(name: string, scheme: OpenApiSecurityScheme): this;
+    generate(): OpenApiDocument;
+    private getControllerMeta;
+    private getControllerRoutes;
+    private getControllerTags;
+    private isControllerExcluded;
+    private isControllerDeprecated;
+    private isEndpointExcluded;
+    private isEndpointDeprecated;
+    private getOperationMetadata;
+    private getResponseMetadata;
+    private getBodyMetadata;
+    private getSwaggerParamMetadata;
+    private getQueryMetadata;
+    private getHeaderMetadata;
+    private getSecurityMetadata;
+    private getMethodTags;
+    private getHttpStatusCode;
+    private getCoreParams;
+    private normalizePath;
+    private buildOperation;
+    private buildParameters;
+    private extractPathParams;
+    private buildRequestBody;
+    private buildResponses;
+    private getDefaultStatusDescription;
+    private buildSecuritySchemes;
+}
+
+declare function isZodSchema(value: unknown): value is ZodType<unknown>;
+declare function zodToOpenApi(schema: ZodType): OpenApiSchemaObject;
+declare function toOpenApiSchema(schemaOrOpenApi: ZodType | OpenApiSchemaObject | undefined): OpenApiSchemaObject | undefined;
+
+type Constructor<T = unknown> = new (...args: any[]) => T;
+interface SwaggerPluginOptions {
+    config?: SwaggerConfig;
+    info?: OpenApiInfoObject;
+    controllers?: Constructor[];
+    jsonPath?: string;
+    uiPath?: string;
+    exposeUI?: boolean;
+    exposeSpec?: boolean;
+    logo?: {
+        url: string;
+        altText?: string;
+        backgroundColor?: string;
+    };
+    theme?: 'default' | 'dark';
+    transform?: (spec: OpenApiDocument) => OpenApiDocument | Promise<OpenApiDocument>;
+}
+declare module 'fastify' {
+    interface FastifyInstance {
+        openApiSpec?: OpenApiDocument;
+    }
+}
+declare const swaggerPlugin: FastifyPluginAsync<SwaggerPluginOptions>;
+declare function registerSwagger(app: FastifyInstance, options?: SwaggerPluginOptions): Promise<void>;
+declare function createSwaggerConfig(options?: SwaggerPluginOptions): {
+    swaggerOptions: {
+        mode: 'static';
+        specification: {
+            document: OpenApiDocument;
+        };
+    };
+    swaggerUIOptions: FastifySwaggerUiOptions;
+    specification: OpenApiDocument;
+};
+
+export { API_BODY_METADATA, API_DEPRECATED_METADATA, API_EXCLUDE_METADATA, API_HEADER_METADATA, API_OPERATION_METADATA, API_PARAM_METADATA, API_PROPERTY_METADATA, API_QUERY_METADATA, API_RESPONSE_METADATA, API_SECURITY_METADATA, API_TAGS_METADATA, ApiAcceptedResponse, ApiBadRequestResponse, ApiBasicAuth, ApiBearerAuth, ApiBody, type ApiBodyOptions, ApiConflictResponse, ApiCookieAuth, ApiCreatedResponse, ApiDeprecated, ApiExcludeController, ApiExcludeEndpoint, ApiForbiddenResponse, ApiHeader, type ApiHeaderOptions, ApiHideProperty, ApiInternalServerErrorResponse, ApiNoContentResponse, ApiNotFoundResponse, ApiOAuth2, ApiOkResponse, ApiOperation, type ApiOperationOptions, ApiParam, type ApiParamOptions, ApiProperty, ApiPropertyOptional, type ApiPropertyOptions, ApiQuery, type ApiQueryOptions, ApiResponse, type ApiResponseOptions, ApiSecurity, type ApiSecurityOptions, ApiTags, ApiUnauthorizedResponse, ApiUnprocessableEntityResponse, type Constructor$2 as Constructor, type ExtractedRouteInfo, type OpenApiDataType, type OpenApiDocument, type OpenApiFormat, OpenApiGenerator, type OpenApiInfoObject, type OpenApiOperation, type OpenApiParameterObject, type OpenApiPathItem, type OpenApiRequestBodyObject, type OpenApiResponseObject, type OpenApiSchemaObject, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type ParameterLocation, type StoredParamMetadata, type StoredResponseMetadata, type SwaggerConfig, type SwaggerContactConfig, type SwaggerExternalDocsConfig, type SwaggerLicenseConfig, type SwaggerServerConfig, type SwaggerTagConfig, createSwaggerConfig, getApiBody, getApiDeprecated, getApiHeaders, getApiOperation, getApiParams, getApiProperties, getApiQueries, getApiResponses, getApiSecurity, getApiTags, isApiExcluded, isZodSchema, registerSwagger, swaggerPlugin, toOpenApiSchema, zodToOpenApi };