feat: path/method description decorator

Author: Sorikairox

decorators.ts

@@ -161,6 +161,44 @@ return (
 };
 }
 
+/**
+ * A constant key used to store or retrieve description metadata.
+ * This key is typically used in decorators to annotate
+ * classes or methods with specific description for documentation.
+ */
+export const DESCRIPTION_KEY = 'description';
+
+/**
+ * A decorator function to add an openAPI description to a class or a method.
+ *
+ * @param description - The description.
+ *
+ * @example
+ * ```typescript
+ * class ExampleClass {
+ *   @Description('My very cool description')
+ *   exampleMethod() {
+ *     // method implementation
+ *   }
+ * }
+ * ```
+ */
+export function Description(description: string) : DecoratorFunction {
+	return (
+		target: Object,
+		propertyKey?: string | symbol,
+		descriptor?: PropertyDescriptor,
+	) => {
+		if (propertyKey) {
+			MetadataHelper.setMetadata(DESCRIPTION_KEY, description, target, propertyKey);
+		} else {
+			MetadataHelper.setMetadata(DESCRIPTION_KEY, description, target);
+		}
+	};
+	}
+
+
+
 /**
  * A constant key used to store or retrieve api-security metadata.
  */

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@danet/swagger",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "exports": {
     ".":"./mod.ts",
     "./decorators": "./decorators.ts"

example/app.ts

@@ -2,6 +2,7 @@ import {
 	ApiBasicAuth, ApiBearerAuth, ApiCookieAuth, ApiOAuth2,
 	ApiProperty, ApiSecurity,
 	BodyType,
+	Description,
 	Optional,
 	QueryType,
 	ReturnedType,
@@ -181,6 +182,7 @@ class MyController {
 @Tag('second')
 @Controller('second-endpoint')
 class SecondController {
+	@Description("Get Second Description")
 	@ApiSecurity('basic')
 	@Get()
 	getSecond() {

method-definer.ts

@@ -1,6 +1,6 @@
 import { Swagger } from './swagger.ts';
 import { Constructor } from './mod.ts';
-import { API_PROPERTY, API_SECURITY, OPTIONAL_KEY, RETURNED_TYPE_KEY, TAGS_KEY } from './decorators.ts';
+import { API_PROPERTY, API_SECURITY, DESCRIPTION_KEY, OPTIONAL_KEY, RETURNED_TYPE_KEY, TAGS_KEY } from './decorators.ts';
 import { RequestBodyBuilder, ResponseBuilder } from './builder.ts';
 import DataType = Swagger.DataType;
 import DataFormat = Swagger.DataFormat;
@@ -70,6 +70,7 @@ export class MethodDefiner {
 		this.addResponse(actualPath);
 		this.addRequestBody(actualPath);
 		this.addSecurity(actualPath);
+		this.addDescription(actualPath);
 		schemas = {
 			...schemas,
 			...this.schemas,
@@ -117,6 +118,17 @@ export class MethodDefiner {
 		}
 	}
 
+	private addDescription(actualPath: Operation) {
+		const methodDescription = MetadataHelper.getMetadata<string>(
+			DESCRIPTION_KEY,
+			this.Controller.prototype,
+			this.methodName,
+		);
+		if (methodDescription) {
+			actualPath.description = methodDescription;
+		}
+	}
+
 	private addUrlParams(actualPath: Operation) {
 		if (this.containsUrlParams && !actualPath.parameters) {
 			actualPath.parameters = [];

spec/generate-schemas.test.ts

@@ -84,6 +84,7 @@ const expectedSpec = {
 		'/second-endpoint': {
 			'get': {
 				'operationId': 'getSecond',
+				'description': "Get Second Description",
 				'responses': { '200': { 'description': '' } },
 				'tags': ['second'],
 				'security': [{