Merge pull request #176 from Devansh-bit/api-annotations

Updated docs for several API routes
kossiitkgp · Dec 17, 2023 · 97f0216 · 97f0216
2 parents 3880e12 + 63d3f70
commit 97f0216
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 0 deletions.
diff --git a/controllers/index.go b/controllers/index.go
@@ -6,6 +6,14 @@ import (
 	"net/http"
 )
 
+// Index godoc
+//
+//	@Summary		Checks api health
+//	@Description	Returns a simple string to check if the api is up and running
+//	@Accept			plain
+//	@Produce		plain
+//	@Success		200	{string}	string	"Hello from KOSS Backend!"
+//	@Router			/api [get]
 func Index(w http.ResponseWriter, r *http.Request) {
 	fmt.Fprintf(w, "Hello from KOSS Backend!")
 }
diff --git a/controllers/mentor.go b/controllers/mentor.go
@@ -139,6 +139,16 @@ func RegisterMentor(w http.ResponseWriter, r *http.Request) {
 	utils.RespondWithHTTPMessage(r, w, http.StatusOK, "Mentor registration successful.")
 }
 
+// FetchAllMentors godoc
+//
+//	@Summary		Fetches all mentors
+//	@Description	Fetches the public details for all the mentors
+//	@Accept			plain
+//	@Produce		json
+//	@Success		200	{object}	[]Mentor	"Mentor fetch successful"
+//	@Failure		500	{object}	utils.HTTPMessage	"Database Error fetching mentors"
+//	@Security		JWT
+//	@Router			/mentor/all [get]
 func FetchAllMentors(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db
@@ -225,6 +235,17 @@ func CreateMentorDashboard(mentor models.Mentor, db *gorm.DB) MentorDashboard {
 	}
 }
 
+// FetchMentorDashboard godoc
+//
+//	@Summary		Fetches the mentor dashboard
+//	@Description	Fetches the required details for the mentor dashboard
+//	@Accept			plain
+//	@Produce		json
+//	@Success		200	{object}	MentorDashboard	    "Mentor dashboard details fetched successfuly."
+//	@Failure		400	{object}	utils.HTTPMessage	"Mentor `username` does not exists."
+//	@Failure		500	{object}	utils.HTTPMessage	"Database Error fetching mentor with username `username`"
+//	@Security		JWT
+//	@Router			/mentor/dashboard/ [get]
 func FetchMentorDashboard(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db
@@ -264,6 +285,20 @@ func FetchMentorDashboard(w http.ResponseWriter, r *http.Request) {
 	utils.RespondWithJson(r, w, mentor)
 }
 
+// UpdateMentorDetails godoc
+//
+//	@Summary		Update Mentor Details
+//	@Description	Update mentor details for logged in mentor
+//	@Accept			json
+//	@Produce		json
+//	@Param			request	body		UpdateMentorReqFields	true	"Fields required for Mentor update."
+//	@Success		200		{object}	[]string	"Succesfully updated mentor details."
+//	@Failure		400		{object}	utils.HTTPMessage	"Error decoding JSON body."
+//	@Failure		400		{object}	utils.HTTPMessage	"Mentor `username` does not exists."
+//	@Failure		400		{object}	utils.HTTPMessage	"Invalid Details: Could not update mentor details"
+//	@Security		JWT
+//
+//	@Router			/mentor/form [put]
 func UpdateMentorDetails(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db
@@ -315,6 +350,16 @@ func UpdateMentorDetails(w http.ResponseWriter, r *http.Request) {
 	utils.RespondWithJson(r, w, []string{"Mentor details updated successfully."})
 }
 
+// GetMentorDetails godoc
+//
+//	@Summary		Fetch Mentor Details
+//	@Description	Get mentor details for logged in mentor
+//	@Accept			plain
+//	@Produce		json
+//	@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]
 func GetMentorDetails(w http.ResponseWriter, r *http.Request) {
 	app := r.Context().Value(middleware.APP_CTX_KEY).(*middleware.App)
 	db := app.Db