@nestjs/swagger#ApiParam TypeScript Examples

@ApiOkResponse({
    schema: {
      type: 'object',
      properties: {
        data: {
          $ref: getSchemaPath(User),
        },
      },
    },
    description: '200. Success. Returns a user',
  })
  @ApiNotFoundResponse({
    description: '404. NotFoundException. User was not found',
  })
  @ApiUnauthorizedResponse({
    schema: {
      type: 'object',
      example: {
        message: 'string',
      },
    },
    description: '401. UnauthorizedException.',
  })
  @ApiParam({ name: 'id', type: String })
  @Get(':id')
  @Serialize(UserResponseDto)
  @Auth()
  async getById(
    @Param('id', ParseObjectIdPipe) id: Types.ObjectId,
  ): Promise<User> {
    const foundUser = await this.usersService.getVerifiedUserById(id);

    if (!foundUser) {
      throw new NotFoundException('The user does not exist');
    }

    return foundUser;
  }

@Put('/:courseId/:assignmentId')
  @Roles(Role.ADMIN)
  @ApiParam(courseId)
  @ApiOperation({ summary: 'update an Assignment' })
  @ApiOkResponse(responsedoc.updateAssignment)
  async updateAssignment(
    @Param('courseId') courseId: Schema.Types.ObjectId,
    @Param('assignmentId') assignmentId: Schema.Types.ObjectId,
    @Body() updateAssignmentDTO: UpdateAssignmentDTO,
  ) {
    return await this.assignmentService.updateAssignment(
      courseId,
      assignmentId,
      updateAssignmentDTO,
    );
  }

@ApiBearerAuth()
  @ApiNestNotFoundResponse('No user was found with the specified id')
  @ApiOperation({ summary: 'Deletes specified user' })
  @ApiParam({ name: 'id', example: 1 })
  @OverrideLevelAccess(AdminLevel.SuperAdmin)
  @Delete(':id')
  delete(@Param('id', ParseIntPipe) id: number): Promise<void> {
    return this.usersService.delete(id);
  }

@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);
  }

/**
   * Enable one user
   * @param ids User ID integer
   * @example DELETE /users/1/enable
   */
  @ApiTags('Users single operation')
  @ApiOperation({
    summary: 'Enable user - Batch',
    description: 'Enable user. You will have to provide a query param of ids separated by comas example: ?ids=1,2,3',
  })
  @ApiOkResponse({ status: 200, description: 'Success response' })
  @ApiUnauthorizedResponse({ status: 401, description: 'Unauthorized' })
  @ApiBadGatewayResponse({ status: 502, description: 'Something happened' })
  @ApiParam({ name: 'id', required: true, type: 'number', example: '1' })
  @Patch(':id/enable')
  async enable(@Param('id') id: number) {
    return await this.service.enable(id);
  }

@ApiOperation({ summary: 'Gets a specific User' })
  @ApiParam({ description: 'Unique User identifier', name: 'id' })
  @Get(':id')
  async get(
    @Param('id', new IntIsSafeForPrismaPipe())
    id: number,
  ): Promise<SerializedUserWithRank> {
    const user = await this.usersService.findOrThrow(id);
    const userPoints = await this.userPointsService.findOrThrow(user.id);
    return serializedUserFromRecordWithRank(
      user,
      userPoints,
      await this.usersService.getRank(user),
    );
  }

@Put('/assign/:mentorId')
  @Roles(Role.ADMIN)
  @ApiParam(mentorId)
  @ApiOperation({ summary: 'assign course to mentor' })
  @ApiOkResponse(responsedoc.updateMentor)
  async assignCourseToMentor(
    @Param('mentorId') mentorId: Schema.Types.ObjectId,
    @Body() courseId: Schema.Types.ObjectId,
  ) {
    return await this.mentorService.assignCourseToMentor(mentorId, courseId);
  }

@ApiBearerAuth()
  @ApiNestNotFoundResponse('No survey media was found with the specified id')
  @ApiOperation({ summary: 'Deletes a specified survey media' })
  @ApiParam({ name: 'siteId', example: 1 })
  @ApiParam({ name: 'id', example: 1 })
  @Delete('media/:id')
  deleteMedia(
    @Param('siteId', ParseIntPipe) siteId: number,
    @Param('id', ParseIntPipe) mediaId: number,
  ): Promise<void> {
    return this.surveyService.deleteMedia(mediaId);
  }

@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,
    );
  }

@ApiNestNotFoundResponse('No surveys were found with the specified sensor id')
  @ApiOperation({
    summary: 'Get surveys and survey media from a specified sensor',
  })
  @ApiParam({ name: 'id', example: 'SPOT-0000' })
  @Get(':id/surveys')
  findSensorSurveys(@Param('id') sensorId: string) {
    return this.coralAtlasService.findSensorSurveys(sensorId);
  }

@ApiOkResponse({
    schema: {
      type: 'object',
      properties: {
        data: {
          $ref: getSchemaPath(UserEntity),
        },
      },
    },
    description: '200. Success. Returns a user',
  })
  @ApiNotFoundResponse({
    description: '404. NotFoundException. User was not found',
  })
  @ApiUnauthorizedResponse({
    schema: {
      type: 'object',
      example: {
        message: 'string',
      },
    },
    description: '401. UnauthorizedException.',
  })
  @ApiParam({ name: 'id', type: String })
  @Get(':id')
  @UseGuards(JwtAccessGuard)
  @Serialize(UserResponseEntity)
  async getById(
    @Param('id', ParseIntPipe) id: number,
  ): Promise<UserEntity | never> {
    const foundUser = await this.usersService.getVerifiedUserById(id);

    if (!foundUser) {
      throw new NotFoundException('The user does not exist');
    }

    return foundUser;
  }

@ApiBearerAuth()
  @ApiNestNotFoundResponse('No site was found with the specified id')
  @ApiOperation({ summary: 'Deletes specified site' })
  @ApiParam({ name: 'siteId', example: 1 })
  @UseGuards(IsSiteAdminGuard)
  @Delete(':siteId')
  delete(@Param('siteId', ParseIntPipe) id: number): Promise<void> {
    return this.sitesService.delete(id);
  }

@ApiOkResponse({
    schema: {
      type: 'object',
      properties: {
        data: {
          $ref: getSchemaPath(UserEntity),
        },
      },
    },
    description: '200. Success. Returns a user',
  })
  @ApiNotFoundResponse({
    description: '404. NotFoundException. User was not found',
  })
  @ApiUnauthorizedResponse({
    schema: {
      type: 'object',
      example: {
        message: 'string',
      },
    },
    description: '401. UnauthorizedException.',
  })
  @ApiParam({ name: 'id', type: String })
  @Get(':id')
  @UseGuards(JwtAccessGuard)
  @Serialize(AllUsersResponseEntity)
  async getById(
    @Param('id', ParseIntPipe) id: number,
  ): Promise<SuccessResponseInterface> {
    const foundUser = await this.usersService.getVerifiedUserById(id);

    if (!foundUser) {
      throw new NotFoundException('The user does not exist');
    }

    return ResponseUtils.success(
      'users',
      foundUser,
    );
  }

@ApiBearerAuth()
  @ApiNestNotFoundResponse('No region was found with the specified id')
  @ApiOperation({ summary: 'Deletes specified region' })
  @ApiParam({ name: 'id', example: 1 })
  @Delete(':id')
  delete(@Param('id', ParseIntPipe) id: number): Promise<void> {
    return this.regionsService.delete(id);
  }

@ApiOkResponse({
    schema: {
      type: 'object',
      properties: {
        data: {
          $ref: getSchemaPath(User),
        },
      },
    },
    description: '200. Success. Returns a user',
  })
  @ApiNotFoundResponse({
    description: '404. NotFoundException. User was not found',
  })
  @ApiUnauthorizedResponse({
    schema: {
      type: 'object',
      example: {
        message: 'string',
      },
    },
    description: '401. UnauthorizedException.',
  })
  @ApiParam({ name: 'id', type: String })
  @Get(':id')
  @Serialize(UserResponseDto)
  @Auth()
  async getById(
    @Param('id', ParseObjectIdPipe) id: Types.ObjectId,
  ): Promise<UserResponseDto> {
    const foundUser = await this.usersService.getVerifiedUserById(id);

    if (!foundUser) {
      throw new NotFoundException('The user does not exist');
    }

    return ResponseUtils.success(
      'users',
      foundUser,
    );
  }

@ApiOperation({ summary: "Returns all site's survey" })
  @ApiParam({ name: 'siteId', example: 1 })
  @Public()
  @Get()
  find(@Param('siteId', ParseIntPipe) siteId: number): Promise<Survey[]> {
    return this.surveyService.find(siteId);
  }

@Delete('/delete/:mentorId')
  @Roles(Role.ADMIN)
  @ApiParam(mentorId)
  @ApiOperation({ summary: 'Delete a Mentor' })
  @ApiOkResponse(responsedoc.deleteMentor)
  async deleteMentor(@Param('mentorId') mentorId: Schema.Types.ObjectId) {
    return await this.mentorService.deleteMentor(mentorId);
  }

@ApiNestNotFoundResponse('No region was found with the specified id')
  @ApiOperation({ summary: 'Returns specified region' })
  @ApiParam({ name: 'id', example: 1 })
  @Public()
  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number): Promise<Region> {
    return this.regionsService.findOne(id);
  }

@Get('get/:mentorId')
  @ApiParam(mentorId)
  @ApiOkResponse(responsedoc.getMentor)
  @ApiOperation({ summary: 'Fetch a particular Mentor using ID' })
  async getMentor(@Param('mentorId') mentorId: Schema.Types.ObjectId) {
    return await this.mentorService.findMentorById(mentorId);
  }

@ApiNestNotFoundResponse('No site was found with the specified id')
  @ApiOperation({ summary: 'Returns specified site' })
  @ApiParam({ name: 'id', example: 1 })
  @Public()
  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number): Promise<Site> {
    return this.sitesService.findOne(id);
  }

@ApiOperation({ summary: 'Gets metrics for a specific User' })
  @ApiParam({ description: 'Unique User identifier', name: 'id' })
  @Get(':id/metrics')
  async metrics(
    @Param('id', new IntIsSafeForPrismaPipe())
    id: number,
    @Query(
      new ValidationPipe({
        errorHttpStatusCode: HttpStatus.UNPROCESSABLE_ENTITY,
        transform: true,
      }),
    )
    query: UserMetricsQueryDto,
  ): Promise<SerializedUserMetrics> {
    const { isValid, error } = this.isValidMetricsQuery(query);
    if (!isValid) {
      throw new UnprocessableEntityException(error);
    }

    const user = await this.usersService.findOrThrow(id);

    let eventMetrics: Record<EventType, SerializedEventMetrics>;
    let points: number;
    let pools: Record<MetricsPool, SerializedEventMetrics> | undefined;
    let nodeUptime: SerializedUserMetrics['node_uptime'];

    if (query.granularity === MetricsGranularity.LIFETIME) {
      eventMetrics = await this.eventsService.getLifetimeEventMetricsForUser(
        user,
      );

      pools = {
        main: await this.eventsService.getLifetimeEventsMetricsForUser(user, [
          EventType.BUG_CAUGHT,
          EventType.NODE_UPTIME,
          EventType.SEND_TRANSACTION,
        ]),
        code: await this.eventsService.getLifetimeEventsMetricsForUser(user, [
          EventType.PULL_REQUEST_MERGED,
        ]),
      };

      const uptime = await this.nodeUptimeService.get(user);
      nodeUptime = {
        total_hours: uptime?.total_hours ?? 0,
        last_checked_in: uptime?.last_checked_in?.toISOString() ?? null,
      };

      const userPoints = await this.userPointsService.findOrThrow(user.id);
      points = userPoints.total_points;
    } else {
      if (query.start === undefined || query.end === undefined) {
        throw new UnprocessableEntityException(
          'Must provide time range for "TOTAL" requests',
        );
      }

      ({ eventMetrics, points } =
        await this.eventsService.getTotalEventMetricsAndPointsForUser(
          user,
          query.start,
          query.end,
        ));
    }

    return {
      user_id: id,
      granularity: query.granularity,
      points,
      pools,
      node_uptime: nodeUptime,
      metrics: {
        blocks_mined: eventMetrics[EventType.BLOCK_MINED],
        bugs_caught: eventMetrics[EventType.BUG_CAUGHT],
        community_contributions: eventMetrics[EventType.COMMUNITY_CONTRIBUTION],
        pull_requests_merged: eventMetrics[EventType.PULL_REQUEST_MERGED],
        social_media_contributions:
          eventMetrics[EventType.SOCIAL_MEDIA_PROMOTION],
        node_uptime: eventMetrics[EventType.NODE_UPTIME],
        send_transaction: eventMetrics[EventType.SEND_TRANSACTION],
      },
    };
  }