Skip to content

Commit

Permalink
feat: path/method description decorator
Browse files Browse the repository at this point in the history
  • Loading branch information
Sorikairox committed Dec 15, 2024
1 parent f961714 commit 3ec51d9
Show file tree
Hide file tree
Showing 5 changed files with 55 additions and 2 deletions.
38 changes: 38 additions & 0 deletions decorators.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down
2 changes: 1 addition & 1 deletion deno.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@danet/swagger",
"version": "2.3.0",
"version": "2.3.1",
"exports": {
".":"./mod.ts",
"./decorators": "./decorators.ts"
Expand Down
2 changes: 2 additions & 0 deletions example/app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import {
ApiBasicAuth, ApiBearerAuth, ApiCookieAuth, ApiOAuth2,
ApiProperty, ApiSecurity,
BodyType,
Description,
Optional,
QueryType,
ReturnedType,
Expand Down Expand Up @@ -181,6 +182,7 @@ class MyController {
@Tag('second')
@Controller('second-endpoint')
class SecondController {
@Description("Get Second Description")
@ApiSecurity('basic')
@Get()
getSecond() {
Expand Down
14 changes: 13 additions & 1 deletion method-definer.ts
Original file line number Diff line number Diff line change
@@ -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;
Expand Down Expand Up @@ -70,6 +70,7 @@ export class MethodDefiner {
this.addResponse(actualPath);
this.addRequestBody(actualPath);
this.addSecurity(actualPath);
this.addDescription(actualPath);
schemas = {
...schemas,
...this.schemas,
Expand Down Expand Up @@ -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 = [];
Expand Down
1 change: 1 addition & 0 deletions spec/generate-schemas.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ const expectedSpec = {
'/second-endpoint': {
'get': {
'operationId': 'getSecond',
'description': "Get Second Description",
'responses': { '200': { 'description': '' } },
'tags': ['second'],
'security': [{
Expand Down

0 comments on commit 3ec51d9

Please sign in to comment.