Swagger

API Operation

@ApiOperation({
    summary: "Verifies the users email",
    description: "Using a token sent to their email when sign up",
})

In the summary we should add annotations like [Public], [Roles:Admin], [Permissions: OWN_TEAM] e.g. [Public] Verifies the users email

API Responses

Swagger API responses are in the form

@ApiResponse({
    status: HttpStatus.<Status>,
    description: "",
    type: <response>
})

type would be a generic Exception in src/global/responses/errors.ts unless for special cases which needs more specific error responses

Here are some examples of API Responses

@ApiResponse({
    status: HttpStatus.OK,
    description: "Successfully gets the forms from the database",
    type: FormResponse,
    isArray: true,
})
@ApiResponse({
    status: HttpStatus.OK,
    description:
    "User successfully authenticated, jwt token is saved in cookies",
    type: LoginResponse,
})
@ApiResponse({
    status: HttpStatus.BAD_REQUEST,
    description:
    "Account does not exist. A more generic error message " +
    "so users can't tell if the account exist or not due to privacy reason",
    type: BadRequestErrorResponse,
})
@ApiResponse({
    status: HttpStatus.UNAUTHORIZED,
    description: "Login fails. Usually wrong password",
    type: LoginUnauthorizedErrorResponse,
})

Decorators Order

Ideally, all endpoints will follow the order below for consistency
Note: not all routes will have all of the follow decorators

• ApiOperation
• ApiResponses (ascending code, i.e, 200, 201, 400, 401, 403, etc)
• @HttpCode
• @UseGuards
• @Public, @Roles, @Permissions
• @GET, @POST, @DELETE etc