fix(doc): improve operationId generation

etienne-bechara · Feb 16, 2024 · 1ade6bf · 1ade6bf
1 parent 4dd9d4f
commit 1ade6bf
Show file tree

Hide file tree

Showing 5 changed files with 21 additions and 52 deletions.
diff --git a/dev/user/user.controller.ts b/dev/user/user.controller.ts
@@ -1,6 +1,6 @@
 import { Cache } from '../../source/cache/cache.decorator';
 import { ApiTag } from '../../source/doc/doc.decorator';
-import { ApiCreatedResponse, ApiNoContentResponse, ApiOkResponse, ApiOperation, ApiSecurity, Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Query, Response } from '../../source/override';
+import { ApiOperation, ApiSecurity, Body, Controller, Delete, Get, HttpStatus, Param, Patch, Post, Query, Response } from '../../source/override';
 import { UserCreateDto, UserIdDto, UserPageDto, UserReadDto, UserUpdateDto } from './user.dto.in';
 import { UserDto } from './user.dto.out';
 import { UserService } from './user.service';
@@ -21,47 +21,45 @@ export class UserController {
   ) { }
 
   @Get()
-  @Response(UserPageDto)
-  @ApiOkResponse({ type: UserPageDto })
+  @Response(HttpStatus.OK, UserPageDto)
   @ApiOperation({ description: 'Reads the collection of users with pagination support' })
   public getUser(@Query() query: UserReadDto): UserPageDto {
     return this.userService.readUsers(query);
   }
 
   @Get(':id')
-  @ApiOkResponse({ type: UserDto })
-  @ApiOperation({ description: 'Reads a single user by its ID' })
+  @Response(HttpStatus.OK, UserDto)
   @Cache<UserDto>({
     buckets: ({ req, data }) => [ req.params.id, data.address.zip ],
   })
+  @ApiOperation({ description: 'Reads a single user by its ID' })
   public getUserById(@Param() params: UserIdDto): UserDto {
     return this.userService.readUserById(params.id);
   }
 
   @Post()
-  @ApiCreatedResponse({ type: UserDto })
+  @Response(HttpStatus.CREATED, UserDto)
   @ApiOperation({ description: 'Creates a new user' })
   public postUser(@Body() body: UserCreateDto): Promise<UserDto> {
     return this.userService.createUser(body);
   }
 
   @Patch(':id')
-  @ApiOkResponse({ type: UserDto })
-  @ApiOperation({ description: 'Partially updates an existing user by its ID' })
+  @Response(HttpStatus.OK, UserDto)
   @Cache({
     invalidate: ({ req }) => [ req.params.id ],
   })
+  @ApiOperation({ description: 'Partially updates an existing user by its ID' })
   public patchUser(@Param() params: UserIdDto, @Body() body: UserUpdateDto): UserDto {
     return this.userService.updateUserById(params.id, body);
   }
 
   @Delete(':id')
-  @HttpCode(HttpStatus.NO_CONTENT)
-  @ApiNoContentResponse()
-  @ApiOperation({ description: 'Deletes an user by its ID' })
+  @Response(HttpStatus.NO_CONTENT)
   @Cache({
     invalidate: ({ req }) => [ req.params.id ],
   })
+  @ApiOperation({ description: 'Deletes an user by its ID' })
   public deleteUserById(@Param() params: UserIdDto): void {
     return this.userService.deleteUserById(params.id);
   }

diff --git a/dev/zip/zip.controller.ts b/dev/zip/zip.controller.ts
@@ -1,6 +1,6 @@
 import { Cache } from '../../source/cache/cache.decorator';
 import { ApiTag } from '../../source/doc/doc.decorator';
-import { ApiOkResponse, Controller, Get, Param } from '../../source/override';
+import { Controller, Get, HttpStatus, Param, Response } from '../../source/override';
 import { ZipReadDto } from './zip.dto.in';
 import { ZipDto } from './zip.dto.out';
 import { ZipService } from './zip.service';
@@ -19,7 +19,7 @@ export class ZipController {
 
   @Get(':code')
   @Cache({ ttl: 10_000 })
-  @ApiOkResponse({ type: ZipDto })
+  @Response(HttpStatus.OK, ZipDto)
   public getZipCode(@Param() params: ZipReadDto): Promise<ZipDto> {
     return this.zipService.readZip(params.code);
   }

diff --git a/dev/zip/zip.dto.out.ts b/dev/zip/zip.dto.out.ts
@@ -3,7 +3,7 @@ import { UserAddressState } from '../user/user.enum';
 
 export class ZipDto {
 
-  @IsNumberString()
+  @IsString()
   public cep: string;
 
   @IsString()

diff --git a/source/doc/doc.config.ts b/source/doc/doc.config.ts
@@ -8,6 +8,7 @@ export const DOC_DEFAULT_OPTIONS: DocOptions = {
   noAutoAuth: true,
   authBtnText: 'Authenticate',
   authBtnPosSelector: '.sc-gIvpjk:eq(0)',
+  expandResponses: '200,201',
   title: 'API Reference | OpenAPI',
   version: 'v1',
   favicon: 'https://www.openapis.org/wp-content/uploads/sites/3/2016/11/favicon.png',

diff --git a/source/doc/doc.module.ts b/source/doc/doc.module.ts
@@ -105,46 +105,16 @@ export class DocModule {
     return SwaggerModule.createDocument(instance, builder.build(), {
       ignoreGlobalPrefix: true,
       operationIdFactory: (controllerKey: string, methodKey: string) => {
-        const entityName = controllerKey.replace('Controller', '');
-        const defaultId = `${controllerKey}_${methodKey}`;
-        let operationId: string;
-
-        switch (methodKey.slice(0, 3)) {
-          case 'get' : {
-            operationId = `Read ${entityName}`;
-            break;
-          }
-
-          case 'pos' : {
-            operationId = `Create ${entityName}`;
-            break;
-          }
-
-          case 'put' : {
-            operationId = `Replace ${entityName}`;
-            break;
-          }
-
-          case 'pat' : {
-            operationId = `Update ${entityName}`;
-            break;
-          }
+        const titleCase = methodKey.replaceAll(/([A-Z])/g, ' $1');
 
-          case 'del' : {
-            operationId = `Delete ${entityName}`;
-            break;
-          }
-
-          default: {
-            operationId = defaultId;
-          }
-        }
-
-        if (methodKey.includes('Id')) {
-          operationId = `${operationId} by ID`;
-        }
+        const operationId = titleCase
+          .replace('get ', 'Read ')
+          .replace('post ', 'Create ')
+          .replace('patch ', 'Update ')
+          .replace('put ', 'Update ')
+          .replace('delete ', 'Delete ');
 
-        return entityName ? operationId : defaultId;
+        return operationId;
       },
     });
   }