Documentation of API routes using swagger

Author: kaizerpwn

Makefile

@@ -1,5 +1,8 @@
 run:
-	CompileDaemon -command="./homelab-backend"
+	swag init --parseDependency && CompileDaemon -command="./homelab-backend"
 
 run-linux:
-	/home/kaizer/go/bin/CompileDaemon -command="./homelab-backend"
+	/home/kaizer/go/bin/CompileDaemon -command="./homelab-backend"
+
+swag:
+	swag init --parseDependency

controllers/Analytics.controller.go

@@ -7,6 +7,13 @@ import (
 	"github.com/kaizerpwn/homelab-backend/initializers"
 )
 
+// @Summary Get Number of All Devices
+// @Description Retrieves the total number of devices in the database.
+// @Tags analytics
+// @Accept json
+// @Produce json
+// @Success 200 {integer} int64
+// @Router /analytics/devices [get]
 func GetNumberOfAllDevices(c *gin.Context) {
 	// >> Get number of all devices
 	var deviceCount int64
@@ -15,6 +22,13 @@ func GetNumberOfAllDevices(c *gin.Context) {
 	c.IndentedJSON(http.StatusOK, deviceCount)
 }
 
+// @Summary Get Number of All Rooms
+// @Description Retrieves the total number of rooms in the database.
+// @Tags analytics
+// @Accept json
+// @Produce json
+// @Success 200 {integer} int64
+// @Router /analytics/rooms [get]
 func GetNumberOfAllRooms(c *gin.Context) {
 	// >> Get number of all rooms
 	var deviceCount int64
@@ -23,6 +37,13 @@ func GetNumberOfAllRooms(c *gin.Context) {
 	c.IndentedJSON(http.StatusOK, deviceCount)
 }
 
+// @Summary Get Number of Active Devices
+// @Description Retrieves the total number of active devices.
+// @Tags analytics
+// @Accept json
+// @Produce json
+// @Success 200 {integer} int64
+// @Router /analytics/activedevices [get]
 func GetNumberOfActiveDevices(c *gin.Context) {
 	// >> Get number of all inactive devices
 	var deviceCount int64

controllers/Devices.controller.go

@@ -8,13 +8,29 @@ import (
 	"github.com/kaizerpwn/homelab-backend/models"
 )
 
+// @Summary Get all Devices
+// @Description Fetches a list of all devices from the database.
+// @Tags devices
+// @Accept json
+// @Produce json
+// @Success 200 {array} models.Device
+// @Router /devices [get]
 func GetAllDevices(c *gin.Context) {
 	// Get all devices from database
 	var devices []models.Device
 	initializers.DB.Find(&devices)
 	c.IndentedJSON(http.StatusOK, devices)
 }
 
+// @Summary Get a Device by ID
+// @Description Retrieve a device's information by its unique ID.
+// @Tags devices
+// @Accept json
+// @Produce json
+// @Param id path int true "Device ID" Format(int64)
+// @Success 200 {object} models.Device
+// @Failure 404 {string} string "Device with that ID doesn't exist."
+// @Router /devices/{id} [get]
 func GetDeviceById(c *gin.Context) {
 	// >> Get specific device with id given
 

controllers/Rooms.controller.go

@@ -8,6 +8,13 @@ import (
 	"github.com/kaizerpwn/homelab-backend/models"
 )
 
+// @Summary Get all Rooms
+// @Description Fetches a list of all rooms from the database.
+// @Tags rooms
+// @Accept json
+// @Produce json
+// @Success 200 {array} models.Room
+// @Router /rooms [get]
 func GetAllRooms(c *gin.Context) {
 
 	// >> Get all rooms from database
@@ -17,6 +24,15 @@ func GetAllRooms(c *gin.Context) {
 	c.IndentedJSON(http.StatusOK, rooms)
 }
 
+// @Summary Get a Room by ID
+// @Description Retrieve a room's information by its unique ID.
+// @Tags rooms
+// @Accept json
+// @Produce json
+// @Param id path int true "Room ID" Format(int64)
+// @Success 200 {object} models.Room
+// @Failure 404 {string} string "Room with that ID doesn't exist."
+// @Router /rooms/{id} [get]
 func GetAllRoomsByID(c *gin.Context) {
 
 	// >> Get all rooms from database

controllers/User.controller.go

@@ -9,6 +9,15 @@ import (
 	"golang.org/x/crypto/bcrypt"
 )
 
+// @BasePath /api
+
+// @Summary Get all users from the database
+// @Description Fetch all users from the database (administrator permission needed)
+// @Tags users
+// @Accept json
+// @Produce json
+// @Success 200 {array} models.User
+// @Router /users [get]
 func GetAllUsers(c *gin.Context) {
 
 	// >> Get all users from database
@@ -18,6 +27,15 @@ func GetAllUsers(c *gin.Context) {
 	c.IndentedJSON(http.StatusOK, users)
 }
 
+// @Summary Get a User by ID
+// @Description Retrieve a user's information by their unique ID.
+// @Tags users
+// @Accept json
+// @Produce json
+// @Param id path int true "User ID" Format(int64)
+// @Success 200 {object} models.User
+// @Failure 404 {string} string "User with that ID doesn't exist"
+// @Router /users/{id} [get]
 func GetUserByID(c *gin.Context) {
 	id := c.Param("id")
 
@@ -34,6 +52,18 @@ func GetUserByID(c *gin.Context) {
 	c.IndentedJSON(http.StatusOK, user)
 }
 
+// @Summary User Login
+// @Description Authenticates a user based on provided email and password.
+// @Tags users
+// @Accept json
+// @Produce json
+// @Param email body string true "User's email address" Format(email)
+// @Param password body string true "User's password"
+// @Success 200 {object} models.User
+// @Failure 400 {string} string "Bad Request"
+// @Failure 401 {string} string "Invalid Password"
+// @Failure 404 {string} string "User with that credentials doesn't exist."
+// @Router /users/login [post]
 func Login(c *gin.Context) {
 	var body struct {
 		Email    string `json:"email" binding:"required"`
@@ -70,6 +100,22 @@ func Login(c *gin.Context) {
 	}
 }
 
+// @Summary User Registration
+// @Description Creates a new user account with the provided information.
+// @Tags users
+// @Accept json
+// @Produce json
+// @Param name body string true "User's first name"
+// @Param surname body string true "User's last name"
+// @Param email body string true "User's email address" Format(email)
+// @Param password body string true "User's password"
+// @Param city body string true "User's city"
+// @Success 200 {string} string "Account successfully registered."
+// @Failure 400 {string} string "Invalid request data"
+// @Failure 400 {string} string "All fields are required"
+// @Failure 409 {string} string "User already exists."
+// @Failure 500 {string} string "Internal server error."
+// @Router /users/register [post]
 func Register(c *gin.Context) {
 	var body struct {
 		Name     string `json:"name" binding:"required"`