DEV - Generate docs and log code for the user module

[prooflesben]

Overview

Our backend doesn't have the best documentation when it comes to what everything does and api/http specifics. This ticket is here to fix that. One of the first things to be done within this ticket is to write comments for what each method is doing in the service module. Just a simple 1 line purpose statement should do for these. As well as say what the method does we also want to better our logging.

There is currently a logger in the backend that prints things out when the logger is called the purpose of this logger is so that we can monitor how our backend is working without truly knowing each and every line of code that was executed and its results and inputs. Some methods have some logging done in them one of these methods is the login function if you look at the console you can see those logs come out in purple when you log in. The focus of this part of the ticket is to go through the methods and whenever you a substantial/important piece of the method executes log it so anyone running the method can see what the method did and where the method failed if it did fail or if there was a problem.

The other part of this ticket will be making sure the swagger docs work for the backend. Most of the swagger docs setup and features are done automatically because of nestjs strong typing(bless the lord for that). Your main job for this part of the ticket is to ensure that each route is documented in swagger. Which would include the route showing up in the swagger docs, parameters/body is defined and documented, small route description, and all available status codes are documented and have a description. Finally the last part of the swagger part of this ticket is that devs can use the swagger api page to test backend endpoints without needing to use postman. This just means someone can use the swagger docs ui to run the endpoints when they have the information needed as inputs. Make sure to convert the json body inputs to just tags to a full type for better code quality and automatic swagger documentation.

When it comes to the status codes the thing that determines what status code is returned are the errors being thrown if not its usually a success. Look at what error is being returned and what status code corresponds to that nestjs error to do this part of the ticket.

To see an incode example for logging and swagger things the register route and service method has it done.
Logging Example
Swagger Example

Tasks

• Use logging statements/comments to document how the code is functioning
• Write logging statements for all of the methods in the service and controller files of this module
  • You can look at the auth.service login method as an example of what the logging should look like or the general idea
• Ensure all of the routes in the auth module have a entry in the swagger docs
• Ensure each status code is defined with either the exact response or {Error encountered} as the example response
  • For 500 status codes just have the example be Internal Server Error
• Ensure the input to each route is defined and shown in the swagger docs
  • Input can come in the form of parameters or body json.
  • Basically anything that the route needs to function that gets included in the http request needs to be documented and clear to someone without the code by using the swagger docs.
  • Response bodies are serialized into types for nestjs to automatically pick up

Acceptance Criteria

• All service methods have purpose statements
• All service methods have logging
• All routes appear with the proper information in the swagger docs
  • Proper information
    • Route parameters/json body information
    • Route description
    • All status codes are defined with example output
• All routes are testable through swagger UI

Extra Information

Below are a couple of links and helpful info regarding this ticket since some things might be new and confusing.

Swagger docs

To navigate to the swagger docs you should use localhost with the backends port(3001) to access the /api page. AKA go to (http://localhost:3001/api) link after starting up the backend.

[Swagger Nestjs Documentation] (https://docs.nestjs.com/openapi/introduction)

Logging

More logging info and background
Nestjs Logger Docs

HTTP status codes/ Nestjs errors

Info on http status codes
Nestjs error documentation