Merge pull request #181 from Devansh-bit/api-annotations-dev

Update API Annotations for remaining routes

controllers/mentor.go

@@ -361,7 +361,7 @@ func UpdateMentorDetails(w http.ResponseWriter, r *http.Request) {
 //	@Success		200		{object}	models.Mentor				"Mentor details fetched successfuly."
 //	@Failure		400		{object}	utils.HTTPMessage			"Mentor `username` does not exists."
 //	@Security		JWT
-//	@Router			/student/form [post]
+//	@Router			/mentor/ [get]
 func GetMentorDetails(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db

controllers/project_fetch.go

@@ -55,6 +55,15 @@ func newProject(dbProject *models.Project) Project {
 	}
 }
 
+// FetchAllProjects godoc
+//
+//	@Summary		Fetches all Projects
+//	@Description	Fetches the public details for all the Projects
+//	@Accept			plain
+//	@Produce		json
+//	@Success		200	{object}	[]Project	"Projects fetched successfully."
+//	@Failure		500	{object}	utils.HTTPMessage	"Error fetching projects from the database."
+//	@Router			/project/ [get]
 func FetchAllProjects(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db
@@ -83,6 +92,23 @@ func FetchAllProjects(w http.ResponseWriter, r *http.Request) {
 	utils.RespondWithJson(r, w, response)
 }
 
+// FetchProjectDetails godoc
+//
+//	@Summary		Fetches Project Details
+//	@Description	Fetches all the details for the Project with the provided ID provided the logged in user owns the project.
+//	@Accept			plain
+//	@Produce		json
+//	@Param			id	path		int			true	"Project ID"
+//	@Success		200	{object}	Project	            "Project fetched successfully."
+//	@Failure		400	{object}	utils.HTTPMessage	"Project id not found."
+//	@Failure		400	{object}	utils.HTTPMessage	"Error parsing project id."
+//	@Failure		400	{object}	utils.HTTPMessage	"Project with id `id` does not exist."
+//	@Failure		400	{object}	utils.HTTPMessage	"Error: Mentor `mentor` does not own the project with ID `id`."
+//	@Failure		500	{object}	utils.HTTPMessage	"Error fetching project from the database."
+//
+//	@Security		JWT
+//
+//	@Router			/project/{id} [get]
 func FetchProjectDetails(w http.ResponseWriter, r *http.Request) {
 	reqParams := mux.Vars(r)
 

controllers/project_reg.go

@@ -31,6 +31,25 @@ type RegisterProjectReqFields struct {
 	ReadmeLink string `json:"readme_link"`
 }
 
+// RegisterProject godoc
+//
+//	@Summary		Register a Project
+//	@Description	Register a new project with the provided details.
+//	@Accept			json
+//	@Produce		json
+//	@Param			request	body		RegisterProjoectReqFields	true	"Fields required for project registeration"
+//	@Success		200		{object}	utils.HTTPMessage			"Success."
+//	@Failure		401		{object}	utils.HTTPMessage			"Login username and mentor username do not match."
+//	@Failure		400		{object}	utils.HTTPMessage			"Error: Project `project` already exists."
+//	@Failure		400		{object}	utils.HTTPMessage			"Error decoding request JSON body."
+//	@Failure		400		{object}	utils.HTTPMessage			"Error: Mentor `mentor` does not exist."
+//	@Failure		400		{object}	utils.HTTPMessage			"Error: Secondary mentor `secondary_mentor` cannot be same as primary mentor."
+//	@Failure		500		{object}	utils.HTTPMessage			"Error fetching mentor `mentor`."
+//	@Failure		500		{object}	utils.HTTPMessage			"Error fetching secondary mentor `secondary_mentor`."
+//	@Failure		500		{object}	utils.HTTPMessage			"Error adding the project in the database."
+//	@Failure		500		{object}	utils.HTTPMessage			"Database error."
+//	@Security		JWT
+//	@Router			/project/ [post]
 func RegisterProject(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db

controllers/project_update.go

@@ -33,6 +33,28 @@ type UpdateProjectReqFields struct {
 	ReadmeLink string `json:"readme_link"`
 }
 
+// 	UpdateProject godoc
+//
+//	@Summary		Update Project Details
+//	@Description	Update project details for the provided project ID.
+//	@Accept			json
+//	@Produce		json
+//	@Param			request	body		UpdateProjectReqFields	true	"Fields required for Project update."
+//	@Success		200		{object}	utils.HTTPMessage	"Project successfully updated."
+//	@Failure		401		{object}	utils.HTTPMessage	"Login username and mentor username do not match."
+//	@Failure		400		{object}	utils.HTTPMessage	"Error decoding request JSON body."
+//	@Failure		400		{object}	utils.HTTPMessage	"Mentor `username` does not exists."
+//	@Failure		400		{object}	utils.HTTPMessage	"Invalid Details: Could not update mentor details"
+//	@Failure		400		{object}	utils.HTTPMessage	"Error: Project `repo_link` does not exist."
+//	@Failure		400		{object}	utils.HTTPMessage	"Error: Mentor `username` does not own the project with ID `id`."
+// 	@Failure		400		{object}	utils.HTTPMessage	"Error: Secondary mentor `secondary_mentor_username` cannot be same as primary mentor."
+//	@Failure		500		{object}	utils.HTTPMessage	"Error updating the project."
+//	@Failure		500		{object}	utils.HTTPMessage	"Database error."
+//	@Failure		500		{object}	utils.HTTPMessage	"Error fetching secondary mentor `secondary_mentor_username`."
+//
+//	@Security		JWT
+//
+//	@Router			/project/ [put]
 func UpdateProject(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db

controllers/stats_overall.go

@@ -16,6 +16,16 @@ type OverallStats struct {
 	GenTime int64 `json:"gen_time"`
 }
 
+// FetchOverallStats godoc
+//
+//	@Summary		Fetches Overall Stats
+//	@Description	Fetches overall stats from the database.
+//	@Accept			plain
+//	@Produce		json
+//	@Success		200		{object}	[]OverallStats	    "Fetched overall stats successfully."
+//	@Failure		500		{object}	utils.HTTPMessage	"Error fetching stats from the database."
+//
+//	@Router			/stats/overall/ [get]
 func FetchOverallStats(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db

controllers/stats_project.go

@@ -17,6 +17,16 @@ type ProjectStats struct {
 	LinesRemoved uint `json:"lines_removed"`
 }
 
+// FetchAllProjectStats godoc
+//
+//	@Summary		Fetches all Project Stats
+//	@Description	Fetches all project stats from the database.
+//	@Accept			plain
+//	@Produce		json
+//	@Success		200		{object}	[]ProjectStats	"Fetch project stats successfully."
+//	@Failure		500		{object}	utils.HTTPMessage	"Error fetching project stats from the database."
+//
+//	@Router			/stats/projects/ [get]
 func FetchAllProjectStats(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db

controllers/stats_student.go

@@ -17,6 +17,16 @@ type StudentBriefStats struct {
 	LinesRemoved uint `json:"lines_removed"`
 }
 
+// FetchAllStudentStats godoc
+//
+//	@Summary		Fetches all Student Stats
+//	@Description	Fetches all student stats from the database.
+//	@Accept			plain
+//	@Produce		json
+//	@Success		200		{object}	[]StudentBriefStats	"Success."
+//	@Failure		500		{object}	utils.HTTPMessage	"Error fetching student stats from the database."
+//
+//	@Router			/stats/students/ [get]
 func FetchAllStudentStats(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db

models/projects.go

@@ -15,7 +15,7 @@ type Project struct {
 	CommChannel   string `gorm:"column:comm_channel"`
 	ReadmeLink    string `gorm:"column:readme_link"`
 	ProjectStatus bool   `gorm:"default:false;column:project_status"`
-	StatusRemark string `gorm:"default:null;column:status_remark"`
+	StatusRemark  string `gorm:"default:null;column:status_remark"`
 
 	// for stats
 	LastPullTime int64 `gorm:"column:last_pull_time"`