feat: 🔥 full swagger support

full swagger support

apps/backend/src/modules/user/modules/groups/classes/edit-label.dto.ts

@@ -2,7 +2,7 @@ import { ApiProperty } from '@nestjs/swagger';
 import { IsString, MinLength } from 'class-validator';
 
 export class EditLabelDto {
-	@ApiProperty({ type: String, description: 'The new label for a group' })
+	@ApiProperty({ type: String, description: 'The new label for a group', example: 'Yazif Group' })
 	@IsString()
 	@MinLength(1)
 	readonly label!: string;

apps/backend/src/modules/user/modules/groups/delete.controller.ts

@@ -1,6 +1,13 @@
 import { Controller, Delete, HttpCode, HttpStatus, Logger, Param, UseGuards } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiInternalServerErrorResponse,
+	ApiOkResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import { CurrentUserId } from '@/decorators/current-user-id.decorator';
 import { BelongingGroupGuard } from '@/guards/belonging-group.guard';
@@ -17,6 +24,11 @@ export class DeleteController {
 
 	@ApiOperation({ description: 'Deleting a group with provided identifier' })
 	@ApiBearerAuth('access-token')
+	@ApiOkResponse({ description: 'If successfully deleted the group' })
+	@ApiUnauthorizedResponse({
+		description: 'If access token is either missing or invalid, or group does not belong to user',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to delete the group' })
 	@UseGuards(BelongingGroupGuard)
 	@Delete(Routes.DELETE)
 	@HttpCode(HttpStatus.OK)

apps/backend/src/modules/user/modules/groups/edit-label.controller.ts

@@ -1,6 +1,13 @@
 import { Body, Controller, HttpCode, HttpStatus, Logger, Param, Patch, UseGuards } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiInternalServerErrorResponse,
+	ApiOkResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import { CurrentUserId } from '@/decorators/current-user-id.decorator';
 import { BelongingGroupGuard } from '@/guards/belonging-group.guard';
@@ -18,6 +25,11 @@ export class EditLabelController {
 
 	@ApiOperation({ description: "Edit a group's label with a new label and its identifier" })
 	@ApiBearerAuth('access-token')
+	@ApiOkResponse({ description: 'If successfully edited the label of the group' })
+	@ApiUnauthorizedResponse({
+		description: 'If access token is either missing or invalid, or group does not belong to user',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to edit the label of the group' })
 	@UseGuards(BelongingGroupGuard)
 	@Patch(Routes.EDIT_LABEL)
 	@HttpCode(HttpStatus.OK)

apps/backend/src/modules/user/modules/groups/get-all.controller.ts

@@ -1,6 +1,13 @@
 import { Controller, Get, HttpCode, HttpStatus, Logger } from '@nestjs/common';
 import { QueryBus } from '@nestjs/cqrs';
-import { ApiBearerAuth, ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiInternalServerErrorResponse,
+	ApiOkResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import { CurrentUserId } from '@/decorators/current-user-id.decorator';
 
@@ -19,6 +26,10 @@ export class GetAllController {
 	@ApiBearerAuth('access-token')
 	@ApiOperation({ description: 'Get all groups of a user' })
 	@ApiOkResponse({ description: "If successfully got all user's groups", type: GetAllGroupsResponse })
+	@ApiUnauthorizedResponse({
+		description: 'If access token is either missing or invalid',
+	})
+	@ApiInternalServerErrorResponse({ description: "If failed to fetch all user's groups" })
 	@Get(Routes.GET_ALL)
 	@HttpCode(HttpStatus.OK)
 	public async getAll(@CurrentUserId() userId: string): Promise<GetAllGroupsResponse> {

apps/backend/src/modules/user/modules/groups/groups.routes.ts

@@ -1,8 +1,8 @@
 const Routes = {
 	CONTROLLER: 'groups',
-	CREATE: 'create',
-	EDIT_LABEL: 'edit-label/:group_id',
-	DELETE: 'delete/:group_id',
+	CREATE: '',
+	EDIT_LABEL: ':group_id',
+	DELETE: ':group_id',
 	GET_ALL: 'all',
 };
 

apps/backend/src/modules/user/modules/inline-policies/add-rule.controller.ts

@@ -11,7 +11,15 @@ import {
 } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
 import { RealIP } from 'nestjs-real-ip';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiCreatedResponse,
+	ApiInternalServerErrorResponse,
+	ApiOkResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import { CurrentUserId } from '@/decorators/current-user-id.decorator';
 
@@ -30,6 +38,11 @@ export class AddRuleController {
 
 	@ApiOperation({ description: 'Add a new rule for an inline policy' })
 	@ApiBearerAuth('access-token')
+	@ApiCreatedResponse({ description: 'If successfully added the rule' })
+	@ApiUnauthorizedResponse({
+		description: 'If access token is missing or invalid, or the policy does not belong to user',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to add rule' })
 	@UseGuards(BelongingInlinePolicyGuard)
 	@Post(Routes.ADD_RULE)
 	@HttpCode(HttpStatus.CREATED)
@@ -50,6 +63,11 @@ export class AddRuleController {
 
 	@ApiOperation({ description: 'Edit a rule of an inline policy' })
 	@ApiBearerAuth('access-token')
+	@ApiOkResponse({ description: 'If successfully edited the rule' })
+	@ApiUnauthorizedResponse({
+		description: 'If access token is missing or invalid, or the policy does not belong to user',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to edit rule' })
 	@UseGuards(BelongingInlinePolicyGuard)
 	@Patch(Routes.EDIT_RULE)
 	@HttpCode(HttpStatus.OK)

apps/backend/src/modules/user/modules/inline-policies/classes/add-rule.dto.ts

@@ -2,7 +2,11 @@ import { ApiProperty } from '@nestjs/swagger';
 import { IsJSON } from 'class-validator';
 
 export class AddRuleDto {
-	@ApiProperty({ type: String, description: 'Stringified rules object' })
+	@ApiProperty({
+		type: String,
+		description: 'Stringified rules object',
+		example: JSON.stringify({ yazifRule: 'error' }),
+	})
 	@IsJSON()
 	readonly rule!: string;
 }

apps/backend/src/modules/user/modules/inline-policies/classes/create-inline.dto.ts

@@ -3,7 +3,7 @@ import { PolicyLibrary } from '@prisma/client';
 import { IsEnum, IsString, MinLength } from 'class-validator';
 
 export class CreateInlineDto {
-	@ApiProperty({ type: String, description: 'The label of the new inline policy' })
+	@ApiProperty({ type: String, description: 'The label of the new inline policy', example: 'Yazif Policy' })
 	@IsString()
 	@MinLength(1)
 	readonly label!: string;

apps/backend/src/modules/user/modules/inline-policies/classes/remove-rule.dto.ts

@@ -2,7 +2,7 @@ import { ApiProperty } from '@nestjs/swagger';
 import { IsString, MinLength } from 'class-validator';
 
 export class RemoveRuleDto {
-	@ApiProperty({ type: String, description: 'The name of the rule to remove' })
+	@ApiProperty({ type: String, description: 'The name of the rule to remove', example: 'YazifRule' })
 	@IsString()
 	@MinLength(1)
 	readonly ruleName!: string;

apps/backend/src/modules/user/modules/inline-policies/classes/responses.ts

@@ -0,0 +1,18 @@
+import { ApiResponseProperty } from '@nestjs/swagger';
+import { Prisma } from '@prisma/client';
+
+export class CreateInlinePolicyResponse {
+	@ApiResponseProperty({
+		type: String,
+		example: '62e5362119bea07115434f4a',
+	})
+	public policyId!: string;
+}
+
+export class GetConfigurationResponse {
+	@ApiResponseProperty({
+		type: Object,
+		example: { yazifConfig1: 'Yazif', yazifConfig2: 'Yazif 2' },
+	})
+	public configuration!: Prisma.JsonValue;
+}

apps/backend/src/modules/user/modules/inline-policies/classes/update-configuration.dto.ts

@@ -2,7 +2,11 @@ import { ApiProperty } from '@nestjs/swagger';
 import { IsJSON } from 'class-validator';
 
 export class UpdateConfigurationDto {
-	@ApiProperty({ type: String, description: 'Stringified configuration object' })
+	@ApiProperty({
+		type: String,
+		description: 'Stringified configuration object',
+		example: JSON.stringify({ yazifConfig1: 'yazif', yazifConfig2: 'yazifos' }),
+	})
 	@IsJSON()
 	readonly configuration!: string;
 }

apps/backend/src/modules/user/modules/inline-policies/create-inline.controller.ts

@@ -1,15 +1,22 @@
 import { Body, Controller, HttpCode, HttpStatus, Logger, Param, Post, UseGuards } from '@nestjs/common';
 import { QueryBus } from '@nestjs/cqrs';
 import { RealIP } from 'nestjs-real-ip';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiCreatedResponse,
+	ApiInternalServerErrorResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import { CurrentUserId } from '@/decorators/current-user-id.decorator';
 import { BelongingGroupGuard } from '@/guards/belonging-group.guard';
 
 import Routes from './inline-policies.routes';
 import { CreateInlineDto } from './classes/create-inline.dto';
 import { CreateInlineContract } from './queries/contracts/create-inline.contract';
-import type { ICreateInlinePolicy } from './interfaces/responses';
+import { CreateInlinePolicyResponse } from './classes/responses';
 
 @ApiTags('Inline Policies')
 @Controller(Routes.CONTROLLER)
@@ -20,6 +27,14 @@ export class CreateInlineController {
 
 	@ApiOperation({ description: 'Create a new inline policy with label and chosen library' })
 	@ApiBearerAuth('access-token')
+	@ApiCreatedResponse({
+		description: 'If successfully created the policy',
+		type: CreateInlinePolicyResponse,
+	})
+	@ApiUnauthorizedResponse({
+		description: 'If access token is missing or invalid',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to create policy' })
 	@UseGuards(BelongingGroupGuard)
 	@Post(Routes.CREATE)
 	@HttpCode(HttpStatus.CREATED)
@@ -28,7 +43,7 @@ export class CreateInlineController {
 		@Param('group_id') groupId: string,
 		@Body() createInlineDto: CreateInlineDto,
 		@RealIP() ip: string,
-	): Promise<ICreateInlinePolicy> {
+	): Promise<CreateInlinePolicyResponse> {
 		this.logger.log(
 			`Will try to create an inline policy for a user with an Id: "${userId}" and for group with Id: "${groupId}". Label is "${createInlineDto.label}"`,
 		);

apps/backend/src/modules/user/modules/inline-policies/delete-inline.controller.ts

@@ -1,6 +1,13 @@
 import { Controller, Delete, HttpCode, HttpStatus, Logger, Param, UseGuards } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiInternalServerErrorResponse,
+	ApiOkResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import { CurrentUserId } from '@/decorators/current-user-id.decorator';
 
@@ -17,6 +24,11 @@ export class DeleteInlineController {
 
 	@ApiOperation({ description: 'Delete a policy by its identifier' })
 	@ApiBearerAuth('access-token')
+	@ApiOkResponse({ description: 'If successfully deleted the policy' })
+	@ApiUnauthorizedResponse({
+		description: 'If access token is missing or invalid, or policy does not belong to user',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to delete policy' })
 	@UseGuards(BelongingInlinePolicyGuard)
 	@Delete(Routes.DELETE)
 	@HttpCode(HttpStatus.OK)

apps/backend/src/modules/user/modules/inline-policies/get-configuration.controller.ts

@@ -1,13 +1,20 @@
 import { Controller, Get, HttpCode, HttpStatus, Logger, Param, UseGuards } from '@nestjs/common';
 import { QueryBus } from '@nestjs/cqrs';
 import type { Prisma } from '@prisma/client';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiInternalServerErrorResponse,
+	ApiOkResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import { CurrentUserId } from '@/decorators/current-user-id.decorator';
 
 import Routes from './inline-policies.routes';
 import { BelongingInlinePolicyGuard } from './guards/belonging-inline-policy.guard';
-import type { IGetConfigurationResponse } from './interfaces/responses';
+import { GetConfigurationResponse } from './classes/responses';
 import { GetConfigurationContract } from './queries/contracts/get-configuration.contract';
 
 @ApiTags('Inline Policies')
@@ -19,13 +26,21 @@ export class GetConfigurationController {
 
 	@ApiOperation({ description: 'Get the configuration of a policy by its identifer' })
 	@ApiBearerAuth('access-token')
+	@ApiOkResponse({
+		description: 'If successfully fetched the policy configuration',
+		type: GetConfigurationResponse,
+	})
+	@ApiUnauthorizedResponse({
+		description: 'If access token is missing or invalid, or policy does not belong to user',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to fetch policy configuration' })
 	@UseGuards(BelongingInlinePolicyGuard)
 	@Get(Routes.GET_CONFIGURATION)
 	@HttpCode(HttpStatus.OK)
 	public async getConfiguration(
 		@CurrentUserId() userId: string,
 		@Param('policy_id') policyId: string,
-	): Promise<IGetConfigurationResponse> {
+	): Promise<GetConfigurationResponse> {
 		this.logger.log(
 			`Will try to fetch policy configuration belongs to use with an Id: "${userId}" with policy Id: "${policyId}"`,
 		);

apps/backend/src/modules/user/modules/inline-policies/remove-rule.controller.ts

@@ -1,6 +1,13 @@
-import { Body, Controller, Logger, Param, Post, UseGuards } from '@nestjs/common';
+import { Body, Controller, Delete, HttpCode, HttpStatus, Logger, Param, UseGuards } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiInternalServerErrorResponse,
+	ApiOkResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import Routes from './inline-policies.routes';
 import { BelongingInlinePolicyGuard } from './guards/belonging-inline-policy.guard';
@@ -16,8 +23,14 @@ export class RemoveRuleController {
 
 	@ApiOperation({ description: 'Remove a rule (by its name) of a policiy by its identifier' })
 	@ApiBearerAuth('access-token')
+	@ApiOkResponse({ description: 'If successfully deleted the rule' })
+	@ApiUnauthorizedResponse({
+		description: 'If access token is missing or invalid, or policy does not belong to user',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to delete rule' })
 	@UseGuards(BelongingInlinePolicyGuard)
-	@Post(Routes.REMOVE_RULE)
+	@Delete(Routes.REMOVE_RULE)
+	@HttpCode(HttpStatus.OK)
 	public async removeRule(
 		@Param('policy_id') policyId: string,
 		@Body() removeRuleDto: RemoveRuleDto,

apps/backend/src/modules/user/modules/inline-policies/update-configuration.controller.ts

@@ -1,6 +1,13 @@
 import { Body, Controller, HttpCode, HttpStatus, Logger, Param, Patch, UseGuards } from '@nestjs/common';
 import { CommandBus } from '@nestjs/cqrs';
-import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import {
+	ApiBearerAuth,
+	ApiInternalServerErrorResponse,
+	ApiOkResponse,
+	ApiOperation,
+	ApiTags,
+	ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
 
 import Routes from './inline-policies.routes';
 import { BelongingInlinePolicyGuard } from './guards/belonging-inline-policy.guard';
@@ -16,6 +23,11 @@ export class UpdateConfigurationController {
 
 	@ApiOperation({ description: 'Update the configuration of a policy by its identifier' })
 	@ApiBearerAuth('access-token')
+	@ApiOkResponse({ description: 'If successfully update configuration of policy' })
+	@ApiUnauthorizedResponse({
+		description: 'If access token is missing or invalid, or policy does not belong to user',
+	})
+	@ApiInternalServerErrorResponse({ description: 'If failed to update policy configuration' })
 	@UseGuards(BelongingInlinePolicyGuard)
 	@Patch(Routes.UPDATE_CONFIGURATION)
 	@HttpCode(HttpStatus.OK)