/**
 * OpenAPI decorators for documentation and validation
 *
 * These decorators serve dual purposes:
 * 1. Generate OpenAPI 3.1 specification
 * 2. Validate requests at runtime
 */
import type { IOpenApiOperationMeta, IOpenApiParamMeta, IOpenApiRequestBodyMeta, IOpenApiResponseBodyMeta } from '../decorators/decorators.types.js';
/**
 * @ApiOperation - Document the operation with summary and description
 *
 * @example
 * ```typescript
 * @Get('/:id')
 * @ApiOperation({
 *   summary: 'Get user by ID',
 *   description: 'Retrieves a single user by their unique identifier',
 *   operationId: 'getUserById',
 * })
 * getUser(ctx: IRequestContext) { ... }
 * ```
 */
export declare function ApiOperation(options: IOpenApiOperationMeta): <This, Args extends any[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
/**
 * @ApiParam - Document and validate a path parameter
 *
 * @example
 * ```typescript
 * @Get('/:id')
 * @ApiParam('id', {
 *   description: 'User UUID',
 *   schema: { type: 'string', format: 'uuid' }
 * })
 * getUser(ctx: IRequestContext) { ... }
 * ```
 */
export declare function ApiParam(name: string, options?: IOpenApiParamMeta): <This, Args extends any[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
/**
 * @ApiQuery - Document and validate a query parameter
 *
 * Supports type coercion: string query values are converted to the
 * appropriate type based on the schema (integer, number, boolean, array).
 *
 * @example
 * ```typescript
 * @Get('/')
 * @ApiQuery('limit', {
 *   description: 'Maximum number of results',
 *   schema: { type: 'integer', default: 10, minimum: 1, maximum: 100 }
 * })
 * @ApiQuery('active', {
 *   description: 'Filter by active status',
 *   schema: { type: 'boolean' }
 * })
 * listUsers(ctx: IRequestContext) {
 *   // ctx.query.limit is coerced to number
 *   // ctx.query.active is coerced to boolean
 * }
 * ```
 */
export declare function ApiQuery(name: string, options?: IOpenApiParamMeta): <This, Args extends any[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
/**
 * @ApiHeader - Document and validate a header parameter
 *
 * @example
 * ```typescript
 * @Get('/')
 * @ApiHeader('X-Request-ID', {
 *   description: 'Unique request identifier',
 *   schema: { type: 'string', format: 'uuid' }
 * })
 * getData(ctx: IRequestContext) { ... }
 * ```
 */
export declare function ApiHeader(name: string, options?: IOpenApiParamMeta): <This, Args extends any[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
/**
 * @ApiRequestBody - Document and validate the request body
 *
 * The request body is validated against the provided JSON Schema.
 * Invalid requests receive a 400 response before the handler runs.
 *
 * @example
 * ```typescript
 * const CreateUserSchema = {
 *   type: 'object',
 *   properties: {
 *     name: { type: 'string', minLength: 1 },
 *     email: { type: 'string', format: 'email' },
 *   },
 *   required: ['name', 'email'],
 * };
 *
 * @Post('/')
 * @ApiRequestBody({
 *   description: 'User creation payload',
 *   schema: CreateUserSchema
 * })
 * createUser(ctx: IRequestContext<{ name: string; email: string }>) {
 *   // ctx.body is guaranteed to match the schema
 * }
 * ```
 */
export declare function ApiRequestBody(options: IOpenApiRequestBodyMeta): <This, Args extends any[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
/**
 * @ApiResponseBody - Document a response for a specific status code
 *
 * Multiple @ApiResponseBody decorators can be used for different status codes.
 *
 * @example
 * ```typescript
 * @Get('/:id')
 * @ApiResponseBody(200, {
 *   description: 'User found',
 *   schema: UserSchema
 * })
 * @ApiResponseBody(404, {
 *   description: 'User not found'
 * })
 * getUser(ctx: IRequestContext) { ... }
 * ```
 */
export declare function ApiResponseBody(status: number, options: Omit<IOpenApiResponseBodyMeta, 'status'>): <This, Args extends any[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
/**
 * @ApiSecurity - Specify security requirements for a route
 *
 * Can be used on classes (applies to all routes) or methods.
 *
 * @example
 * ```typescript
 * // Method-level security
 * @Post('/')
 * @ApiSecurity('bearerAuth')
 * createUser(ctx: IRequestContext) { ... }
 *
 * // With OAuth scopes
 * @Delete('/:id')
 * @ApiSecurity('oauth2', ['users:delete'])
 * deleteUser(ctx: IRequestContext) { ... }
 * ```
 */
export declare function ApiSecurity(name: string, scopes?: string[]): <T extends (new (...args: any[]) => any) | ((this: any, ...args: any[]) => any)>(target: T, context: ClassDecoratorContext | ClassMethodDecoratorContext) => T;
/**
 * @ApiTag - Group routes under a tag in the documentation
 *
 * Multiple tags can be specified. Applied to all routes in the controller.
 *
 * @example
 * ```typescript
 * @Route('/api/users')
 * @ApiTag('Users')
 * @ApiTag('Admin')
 * class UserController { ... }
 * ```
 */
export declare function ApiTag(...tags: string[]): <TClass extends new (...args: any[]) => any>(target: TClass, context: ClassDecoratorContext<TClass>) => TClass;