@nestjs/swagger#ApiCreatedResponse TypeScript Examples

@Delete('/deleteDoubt/:courseId/:doubtId')
  @ApiParam(courseId)
  @ApiParam(doubtId)
  @ApiCreatedResponse(responsedoc.deleteDoubt)
  async deleteDoubt(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Param('doubtId') doubtId: Schema.Types.ObjectId,
  ): Promise<Doubt> {
    return await this.doubtService.deleteDoubt(courseId, doubtId);
  }

/**
   * Create User  - Single
   * @param dto User Form
   * @example POST /users
   */
  @ApiTags('Users single operation')
  @ApiOperation({ summary: 'Create User  - Single', description: 'Register an user, this can be public or privated.' })
  @ApiCreatedResponse({ status: 201, description: 'User created successfully', type: User })
  @ApiUnauthorizedResponse({ status: 401, description: 'Unauthorized' })
  @ApiBadGatewayResponse({ status: 502, description: 'Something happened' })
  @ApiBadRequestResponse({ status: 400, description: 'You will prompt with the validation issues' })
  @ApiBody({ type: CreateUserDto })
  @Post()
  async createOne(@Body() dto: CreateUserDto): Promise<DataOutput<User>> {
    return { message: 'User created successfully', output: await this.service.create(dto) };
  }

/**
   * Create Users - Batch
   * @param dto User Form but in Array format
   * @example POST /users/bulk
   */
  @ApiTags('Users batch operations')
  @ApiOperation({ summary: 'Create Users - Batch', description: 'Register users in batch.' })
  @ApiCreatedResponse({ status: 201, description: 'Users created successfully', type: User })
  @ApiUnauthorizedResponse({ status: 401, description: 'Unauthorized' })
  @ApiBadGatewayResponse({ status: 502, description: 'Something happened' })
  @ApiBadRequestResponse({ status: 400, description: 'You will prompt with an array with the validation issues' })
  @ApiBody({ type: [CreateUserDto] })
  @Post('bulk')
  async createBulk(@Body(new ParseArrayPipe({ items: CreateUserDto })) dto: CreateUserDto[]): Promise<DataOutput<IUser[]>> {
    return { message: 'Users created successfully', output: await this.service.createBatch(dto) };
  }

/**
   * Login user authentication
   * @param dto User Form
   * @example /auth/login
   */
  @ApiOperation({ summary: 'Login user authentication', description: 'In this way you will get the Token for Bearer authentication' })
  @ApiCreatedResponse({ status: 201, description: 'Login success, you will receive the "accessToken" there' })
  @ApiBadRequestResponse({ status: 400, description: 'Invalid credentials' })
  @ApiForbiddenResponse({ status: 403, description: 'Account is disabled, contact with administrator' })
  @ApiNotFoundResponse({ status: 404, description: 'Your account does not exist' })
  @ApiUnauthorizedResponse({ status: 401, description: 'Unauthorized' })
  @ApiBadGatewayResponse({ status: 502, description: 'Login user authentication' })
  @ApiBody({ type: LoginDto })
  @UseGuards(LocalAuthGuard)
  @Post('auth/login')
  async login(@Request() req, @Body() loginDto: LoginDto) {
    return await this.authService.login(req.user);
  }

@ApiOperation({ summary: 'Add new users' })
  @ApiBody({ type: User, isArray: true, description: 'Info of the users' })
  @ApiCreatedResponse({ description: 'The users were created successfully' })
  @ApiBadRequestResponse({ description: 'The users could not be created' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(RolesGuard)
  @Roles(DefaultRole.Admin)
  @Post('bulk')
  @HttpCode(HttpStatus.CREATED)
  async createBulk(
    @Body(new ParseArrayPipe({ items: User })) users: User[]
  ): Promise<void> {
    try {
      await this.userService.addUsers(users)
    } catch (error) {
      /**
       * Validate database exceptions
       */
      switch(error.code) {
        case POSTGRES.UNIQUE_VIOLATION:
          throw new BadRequestException(ERRORS.UNIQUE_VIOLATION)
        default:
          this.logger.error(error.message, 'ADD_USERS')
          throw new BadRequestException(error.message)
      }
    }
  }

@ApiOperation({ summary: 'Create a user' })
  @ApiBody({ type: User, description: 'User information' })
  @ApiCreatedResponse({ description: 'The user was created successfully' })
  @ApiBadRequestResponse({ description: 'The user could not be created' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @UseGuards(RolesGuard)
  @Roles(DefaultRole.Admin)
  @Post()
  @HttpCode(HttpStatus.CREATED)
  async addUser(
    @Body() user: User
  ): Promise<void> {
    try {
      user.role = new Role({ id: DefaultRole.User })
      await this.userService.addUser(user)
    } catch (error) {
      /**
       * Validate database exceptions
       */
      switch(error.code) {
        case POSTGRES.UNIQUE_VIOLATION:
          throw new BadRequestException(ERRORS.UNIQUE_VIOLATION)
        default:
          this.logger.error(error.message, 'ADD_USER')
          throw new BadRequestException(error.message)
      }
    }
  }

@ApiOperation({ summary: 'Create a new role' })
  @ApiBody({ type: Role, description: 'Role information' })
  @ApiCreatedResponse({ description: 'The role was created successfully' })
  @ApiBadRequestResponse({ description: 'The role could not be created' })
  @ApiForbiddenResponse({ description: 'You do not have the necessary role to perform this action' })
  @Post()
  @HttpCode(HttpStatus.CREATED)
  async addRole(
    @Body() role: Role
  ): Promise<void> {
    try {
      await this.roleService.addRole(role)
    } catch (error) {
      /**
       * Validate database exceptions
       */
      switch(error.code) {
        case POSTGRES.UNIQUE_VIOLATION:
          throw new BadRequestException(ERRORS.UNIQUE_VIOLATION)
        default:
          this.logger.error(error.message, 'ADD_ROLE')
          throw new BadRequestException(error.message)
      }
    }
  }

@ApiOperation({
    summary: 'Upload a file.',
    requestBody: {
      content: {
        'multipart/form-data': {
          schema: {
            type: 'object',
            properties: { file: { type: 'string', format: 'binary' } },
          },
        },
      },
    },
  })
  @ApiConsumes('multipart/form-data')
  @ApiCreatedResponse({
    schema: {
      properties: {
        id: {
          type: 'string',
          example: '5e2b4cb75876c93e38b6e6aa',
        },
      },
    },
  })
  @Post()
  uploadFile(@Req() request: Request): Promise<{ id: string }> {
    return this.appService.upload(request)
  }

@Put('/enrolledCourses/:courseId')
  @ApiOperation({ summary: 'user updating enrolled courses' })
  @ApiCreatedResponse(responsedoc.updateEnrolledCourses)
  async updateEnrolledCourses(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Body() updateEnrolledDto: UpdateEnrolledDTO,
  ) {
    return await this.userService.updateCourse(updateEnrolledDto, courseId);
  }

@Delete('/deleteDoubtAnswer/:doubtId/:doubtAnswerId')
  @ApiParam(doubtAnswerId)
  @ApiParam(doubtId)
  @ApiCreatedResponse(responsedoc.deleteDoubtAnswer)
  @ApiOperation({ summary: 'Delete doubt Answer by id' })
  async deleteDoubtAnswer(
    @Param('doubtId') doubtId: Schema.Types.ObjectId,
    @Param('doubtAnswerId') doubtAnswerId: Schema.Types.ObjectId,
  ): Promise<DoubtAnswer> {
    return await this.doubtService.deleteDoubtAnswer(doubtId, doubtAnswerId);
  }

@Put('/updateDoubtAnswer/:doubtId/:doubtAnswerId')
  @ApiParam(doubtAnswerId)
  @ApiParam(doubtId)
  @ApiCreatedResponse(responsedoc.updateDoubtAnswer)
  @ApiOperation({ summary: 'Edit doubt Answer by id' })
  async editDoubtAnswer(
    @Param('doubtId') doubtId: Schema.Types.ObjectId,
    @Param('doubtAnswerId') doubtAnswerId: Schema.Types.ObjectId,
    @Body() updateDoubtAnswerDto: UpdateDoubtAnswerDto,
  ): Promise<DoubtAnswer> {
    return await this.doubtService.editDoubtAnswer(
      doubtId,
      doubtAnswerId,
      updateDoubtAnswerDto,
    );
  }

@Post('/newAnswer/:doubtId')
  @ApiParam(doubtId)
  @ApiCreatedResponse(responsedoc.addDoubtAnswer)
  @ApiOperation({ summary: 'Add a new doubt Answer' })
  async askNewDoubtAnswer(
    @Param('doubtId') doubtId: Schema.Types.ObjectId,
    @Body() createDoubtAnswerDto: CreateDoubtAnswerDto,
  ): Promise<DoubtAnswer> {
    return await this.doubtService.addNewDoubtAnswer(
      doubtId,
      createDoubtAnswerDto,
    );
  }

@Put('/updateDoubt/:courseId/:doubtId')
  @ApiParam(courseId)
  @ApiParam(doubtId)
  @ApiCreatedResponse(responsedoc.updateDoubt)
  @ApiOperation({ summary: 'Edit doubt by id' })
  async editDoubt(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Param('doubtId') doubtId: Schema.Types.ObjectId,
    @Body() updateDoubtDto: UpdateDoubtDto,
  ): Promise<Doubt> {
    return await this.doubtService.editDoubt(courseId, doubtId, updateDoubtDto);
  }

@Post('/new/:courseId')
  @ApiParam(courseId)
  @ApiCreatedResponse(responsedoc.addDoubt)
  @ApiOperation({ summary: 'Add a new doubt' })
  async askNewDoubt(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Body() createDoubtDto: CreateDoubtDto,
  ): Promise<Doubt> {
    return await this.doubtService.addNewDoubt(courseId, createDoubtDto);
  }

@Post('/newLecture/:scheduleId')
  @Roles(Role.ADMIN)
  @ApiParam(scheduleId)
  @ApiOperation({ summary: 'Create a Lecture' })
  @ApiCreatedResponse(responsedoc.addLecture)
  async addLecture(
    @Param('scheduleId') scheduleId: Schema.Types.ObjectId,
    @Body() createReviewDto: CreateLectureDto,
  ) {
    return await this.courseService.addLecture(scheduleId, createReviewDto);
  }

@Post('')
  @UsePipes(ValidationPipe)
  @ApiCreatedResponse({
    description: 'The option that got created',
    type: Option,
  })
  async saveOptionToQuestion(@Body() createOption: CreateOptionDto) {
    const question = await this.questionService.findQuestionById(
      createOption.questionId,
    );
    const option = await this.optionService.creatOption(createOption, question);
    return { question, createOption, option };
  }

@Post('')
  @UsePipes(ValidationPipe)
  @ApiCreatedResponse({
    description: 'Question added to a quiz',
    type: Question,
  })
  async saveQuestion(@Body() question: CreateQuestionDto): Promise<Question> {
    const quiz = await this.quizService.getQuizById(question.quizId);
    return await this.questionService.createQuestion(question, quiz);
  }

@Post('/register')
  @ApiCreatedResponse({
    description: 'Created user object as response',
    type: User,
  })
  @ApiBadRequestResponse({ description: 'User cannot register. Try again!' })
  async doUserRegistration(
    @Body(SETTINGS.VALIDATION_PIPE)
    userRegister: UserRegisterRequestDto,
  ): Promise<User> {
    return await this.userService.doUserRegistration(userRegister);
  }

@ApiBearerAuth()
  @ApiFileUpload()
  @ApiCreatedResponse({
    description: 'Returns the public url to access the uploaded media',
    schema: {
      type: 'string',
      example:
        'https://storage.googleapis.com/storage/reef-image-1029381082910831.jpg',
    },
  })
  @ApiOperation({ summary: 'Uploads a new survey media' })
  @ApiParam({ name: 'siteId', example: 1 })
  @Post('upload')
  @AcceptFile('file', ['image', 'video'], 'surveys', 'site')
  upload(
    @Param('siteId', ParseIntPipe) siteId: number,
    @UploadedFile('file') file: any,
  ): string {
    // Override file path because file.path provided an invalid google cloud format and HTTPS is not working correctly
    // Correct format of a URL pointing to a google cloud object should be
    // https://storage.googleapis.com/{bucketName}/path/to/object/in/bucket
    return `https://storage.googleapis.com/${process.env.GCS_BUCKET}/${file.filename}`;
  }

@Post()
  @Roles(Role.ADMIN)
  @ApiOperation({ summary: 'add an Announcement' })
  @ApiCreatedResponse(responsedoc.addAnnouncement)
  async addAnnouncement(@Body() CreateAnnouncementDTO: CreateAnnouncementDTO) {
    return await this.announcementService.addAnnouncement(
      CreateAnnouncementDTO,
    );
  }

@Post('/:courseId')
  @Roles(Role.ADMIN)
  @ApiCreatedResponse(responsedoc.addAssignment)
  @ApiParam(courseId)
  @ApiOperation({ summary: 'add an Assignment' })
  async addAssignment(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Body() CreateAssignmentDTO: CreateAssignmentDTO,
  ) {
    return await this.assignmentService.addAssignment(
      courseId,
      CreateAssignmentDTO,
    );
  }

@Post('/schedule/:courseId')
  @Roles(Role.ADMIN)
  @ApiOperation({ summary: 'Create a Schedule' })
  @ApiCreatedResponse(responsedoc.addScheduleCourse)
  @ApiParam(courseId)
  async addScheduleCourse(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Body() createScheduleDto: CreateScheduleDto,
  ) {
    return await this.courseService.addScheduleCourse(
      courseId,
      createScheduleDto,
    );
  }

@Post('/review/:courseId')
  @ApiParam(courseId)
  @ApiOperation({ summary: 'Create a Review' })
  @ApiCreatedResponse(responsedoc.addReview)
  async addReview(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Body() createReviewDto: CreateReviewDto,
  ) {
    return await this.courseService.addReview(courseId, createReviewDto);
  }

@Post('/mentor/:courseId/:mentorId')
  @Roles(Role.ADMIN)
  @ApiOperation({ summary: 'Add a mentor to course' })
  @ApiCreatedResponse(responsedoc.addMentorToCourse)
  @ApiParam(courseId)
  async addMentorToCourse(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Param('mentorId') mentorId: Schema.Types.ObjectId,
  ) {
    return await this.courseService.addMentorToCourse(courseId, mentorId);
  }

@Post()
  @Roles(Role.ADMIN)
  @ApiOperation({ summary: 'add a Mentor' })
  @ApiCreatedResponse(responsedoc.addMentor)
  async addMentor(@Body() CreateMentorDTO: CreateMentorDTO) {
    return await this.mentorService.addMentor(CreateMentorDTO);
  }

@Post()
  @ApiOperation({ summary: 'Create a User' })
  @ApiCreatedResponse(responsedoc.addUser)
  async addUser(@Req() request, @Body() CreateUserDTO: CreateUserDTO) {
    return await this.userService.addUser(request, CreateUserDTO);
  }

@Put('/enrolledCourses')
  @ApiOperation({ summary: 'user enrolling courses' })
  @ApiCreatedResponse(responsedoc.addEnrolledCourses)
  async addEnrolledCourses(@Body() createEnrolledDto: CreateEnrolledDTO) {
    return await this.userService.addCourse(createEnrolledDto);
  }

// Retrieve Chats list
  @ApiCreatedResponse({ type: [ChatResponseBody] })
  @Get()
  async getAllChat() {
    return await this.chatService.getAllChat();
  }

@Put('/wishlist')
  @ApiOperation({ summary: 'Add wishlisted courses' })
  @ApiCreatedResponse(responsedoc.addWishlist)
  async addWishlist(@Body() cId: Schema.Types.ObjectId) {
    return await this.userService.addWishlist(cId);
  }