fix(#2364): Add support for passing parameters to @apioperation

This commit introduces the ability to pass parameters directly to the @apioperation decorator, allowing developers to define path parameters within the decorator itself. This simplifies OpenAPI schema generation and improves developer experience by reducing boilerplate code.

Changes include:
- Added `parameters` option to ApiOperationOptions type
- Updated OperationMetadata to include parameters property
- Modified @apioperation decorator to accept and store parameter metadata
- Added tests to verify parameter handling

This change aligns with common usage patterns for OpenAPI specifications and provides a more intuitive way to define API operations with required parameters.

#closes #2364

Author: Michał Grzegorzewski

packages/openapi-metadata/src/decorators/api-operation.ts

@@ -1,4 +1,8 @@
-import { type OperationMetadata, OperationMetadataStorage } from "../metadata/operation.js";
+import {
+  type OperationMetadata,
+  OperationMetadataStorage,
+  OperationParameterMetadataStorage,
+} from "../metadata/index.js";
 
 export type ApiOperationOptions = OperationMetadata;
 
@@ -11,5 +15,8 @@ export type ApiOperationOptions = OperationMetadata;
 export function ApiOperation(options: ApiOperationOptions): MethodDecorator {
   return (target, propertyKey) => {
     OperationMetadataStorage.defineMetadata(target, options, propertyKey);
+    if (Array.isArray(options.parameters)) {
+      OperationParameterMetadataStorage.mergeMetadata(target, options.parameters, propertyKey);
+    }
   };
 }

packages/openapi-metadata/src/metadata/operation.ts

@@ -1,8 +1,9 @@
 import type { OpenAPIV3 } from "openapi-types";
 import type { HttpMethods } from "../types.js";
 import { createMetadataStorage } from "./factory.js";
+import type { OperationParameterMetadata } from "./operation-parameter.js";
 
-export type OperationMetadata = Omit<OpenAPIV3.OperationObject, "responses"> & {
+export type OperationMetadata = Omit<OpenAPIV3.OperationObject, "responses" | "parameters"> & {
   /**
    * Operation path.
    * Can include parameters.
@@ -13,6 +14,11 @@ export type OperationMetadata = Omit<OpenAPIV3.OperationObject, "responses"> & {
    * Available methods for this operation.
    */
   methods?: HttpMethods[];
+
+  /**
+   * Represents metadata about an operation parameter.
+   */
+  parameters?: OperationParameterMetadata[];
 };
 
 export const OperationMetadataKey = Symbol("Operation");

packages/openapi-metadata/test/decorators.test.ts

@@ -1,11 +1,15 @@
 import "reflect-metadata";
 import {
+  ApiBasicAuth,
+  ApiBearerAuth,
   ApiBody,
   ApiCookie,
+  ApiCookieAuth,
   ApiExcludeController,
   ApiExcludeOperation,
   ApiExtraModels,
   ApiHeader,
+  ApiOauth2,
   ApiOperation,
   ApiParam,
   ApiProperty,
@@ -19,26 +23,40 @@ import {
   ExtraModelsMetadataStorage,
   OperationBodyMetadataStorage,
   OperationMetadataStorage,
+  type OperationParameterMetadata,
   OperationParameterMetadataStorage,
   OperationResponseMetadataStorage,
   OperationSecurityMetadataStorage,
   PropertyMetadataStorage,
 } from "../src/metadata/index.js";
-import { ApiBasicAuth, ApiBearerAuth, ApiCookieAuth, ApiOauth2 } from "../src/decorators/api-security.js";
 
 test("@ApiOperation", () => {
+  const parameters: OperationParameterMetadata[] = [
+    {
+      in: "path",
+      name: "id",
+    },
+  ] as const;
+
   class MyController {
-    @ApiOperation({ summary: "Hello", path: "/test", methods: ["get"] })
+    @ApiOperation({
+      summary: "Hello",
+      path: "/test",
+      methods: ["get"],
+      parameters,
+    })
     operation() {}
   }
 
-  const metadata = OperationMetadataStorage.getMetadata(MyController.prototype, "operation");
-
-  expect(metadata).toEqual({
+  const operationMetadata = OperationMetadataStorage.getMetadata(MyController.prototype, "operation");
+  const parameterMetadata = OperationParameterMetadataStorage.getMetadata(MyController.prototype, "operation");
+  expect(operationMetadata).toEqual({
     summary: "Hello",
     path: "/test",
     methods: ["get"],
+    parameters,
   });
+  expect(parameterMetadata).toEqual(parameters);
 });
 
 test("@ApiBody", () => {