📝 Create missing models for API documentation

api/handlers.go

@@ -68,16 +68,16 @@ func CreateOrUpdateHostname(c *gin.Context, isUpdate bool) {
 	c.JSON(http.StatusOK, gin.H{"hostname": hostname})
 }
 
-// @Summary		Delete a hostname from the database
+//	@Summary		Delete a hostname from the database
-// @Description	List all details for a given category
+//	@Description	List all details for a given category
-// @ID				delete-hostnames-by-category-and-name
+//	@ID				delete-hostnames-by-category-and-name
-// @Produce		json
+//	@Produce		json
-// @Param			category	path	string	true	"Category of the hostname"
+//	@Param			category	path		string							true	"Category of the hostname"
-// @Param			hostname	path	string	true	"Hostname to delete"
+//	@Param			hostname	path		string							true	"Hostname to delete"
-// @Success		200			{json}	json	"Hostname"
+//	@Success		200			{object}	models.SimpleHostnameResponse	"Hostname"
-// @Security		Bearer
+//	@Security		Bearer
-// @Tags			Manipulate existing Hostnames
+//	@Tags			Manipulate existing Hostnames
-// @Router			/{category}/{hostname} [delete]
+//	@Router			/{category}/{hostname} [delete]
 func DeleteHostname(c *gin.Context) {
 	category := c.Param("category")
 	hostname := c.Param("hostname")
@@ -90,15 +90,15 @@ func DeleteHostname(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"hostname": hostname})
 }
 
-// @Summary		Return a list of hosts and their details filtered by category
+//	@Summary		Return a list of hosts and their details filtered by category
-// @Description	List all details for a given category
+//	@Description	List all details for a given category
-// @ID				list-hostnames-by-category
+//	@ID				list-hostnames-by-category
-// @Produce		json
+//	@Produce		json
-// @Param			category	path	string	true	"Category of the hostname"
+//	@Param			category	path	string			true	"Category of the hostname"
-// @Success		200			{json}	json	"Hostname"
+//	@Success		200			{array}	models.Hostname	"An array of responses"
-// @Security		Bearer
+//	@Security		Bearer
-// @Tags			Querying Hostnames
+//	@Tags			Querying Hostnames
-// @Router			/{category} [get]
+//	@Router			/{category} [get]
 func ListHostnamesByCategory(c *gin.Context) {
 	category := c.Param("category")
 
@@ -114,16 +114,16 @@ func ListHostnamesByCategory(c *gin.Context) {
 	c.JSON(http.StatusOK, hostnames)
 }
 
-// @Summary		Return a single hostname by Category and Name
+//	@Summary		Return a single hostname by Category and Name
-// @Description	Return details for a single hostname identified by its category
+//	@Description	Return details for a single hostname identified by its category
-// @ID				get-hostname-by-category-and-name
+//	@ID				get-hostname-by-category-and-name
-// @Produce		json
+//	@Produce		json
-// @Param			category	path	string	true	"Category of the hostname"
+//	@Param			category	path		string			true	"Category of the hostname"
-// @Param			hostname	path	string	true	"Category of the hostname"
+//	@Param			hostname	path		string			true	"Category of the hostname"
-// @Security		Bearer
+//	@Success		200			{object}	models.Hostname	"A single response object"
-// @Success		200	{json}	json	"Hostname"
+//	@Security		Bearer
-// @Tags			Querying Hostnames
+//	@Tags			Querying Hostnames
-// @Router			/{category}/{hostname} [get]
+//	@Router			/{category}/{hostname} [get]
 func GetHostnameByCategoryAndName(c *gin.Context) {
 	category := c.Param("category")
 	hostname := c.Param("hostname")

auth/handlers.go

@@ -11,17 +11,18 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-//	 LoginHandler godoc
+//	LoginHandler godoc
+//
 //	@Summary		User login
 //	@Description	Authenticate user and return JWT token
 //	@Tags			Authentication
 //	@Accept			json
 //	@Produce		json
 //	@Param			loginCredentials	body		models.LoginCredentials	true	"Login Credentials"
-//	@Success		200					{object}	map[string]string		"Successfully authenticated, JWT token returned"
+//	@Success		200					{object}	models.TokenResponse	"Successfully authenticated, JWT token returned"
-//	@Failure		400					{object}	map[string]string		"Invalid request body"
+//	@Failure		400					{object}	models.ErrorResponse	"Invalid request body"
-//	@Failure		401					{object}	map[string]string		"Invalid login credentials"
+//	@Failure		401					{object}	models.ErrorResponse	"Invalid login credentials"
-//	@Failure		500					{object}	map[string]string		"Internal server error"
+//	@Failure		500					{object}	models.ErrorResponse	"Internal server error"
 //	@Router			/login [post]
 func LoginHandler(c *gin.Context) {
 	var creds models.LoginCredentials

models/error.go

@@ -0,0 +1,5 @@
+package models
+
+type ErrorResponse struct {
+	Error string `json:"error"`
+}

models/hostname.go

@@ -6,9 +6,16 @@ import "time"
 // @Description Model of the Hostname as it
 // @Description is represented in the database
 type Hostname struct {
-	ID         int                    `json:"id"`         // Internal ID of the Hostname within the database
+	ID         int                    `json:"Id" example:"25"`                           // Internal ID of the Hostname within the database
-	Category   string                 `json:"category"`   // Category / Rule that was used when generating the hostname
+	Category   string                 `json:"Category" example:"notebook"`               // Category / Rule that was used when generating the hostname
-	Hostname   string                 `json:"hostname"`   // Generated hostname
+	Hostname   string                 `json:"Hostname" example:"ISEHENNB0009"`           // Generated hostname
-	Parameters map[string]interface{} `json:"parameters"` // Parameter object of rule specific attributes
+	Parameters map[string]interface{} `json:"Parameters"`                                // Parameter object of rule specific attributes, see rule.* models
-	CreatedAt  time.Time              `json:"created_at"` // Creation Time of the entry
+	CreatedAt  time.Time              `json:"Created_at" example:"2024-01-16T12:53:59Z"` // Creation Time of the entry
+}
+
+// SimpleHostnameResponse
+// @Description Model of the Hostname as returned by
+// @Description POST endpoint
+type SimpleHostnameResponse struct {
+	Hostname string `json:"Hostname"` // Name of the newly generated host
 }

models/login.go

@@ -4,6 +4,12 @@ package models
 // @Description User account information used in the login process
 // @Description with Username and password
 type LoginCredentials struct {
-	Username string `json:"username"`
+	Username string `json:"Username"`
-	Password string `json:"password"`
+	Password string `json:"Password"`
+}
+
+// JWT Token Response Model
+// @Description Model returned after successful login
+type TokenResponse struct {
+	Token string `json:"token"`
 }

rules/notebook.go

@@ -66,27 +66,27 @@ func (nr *NotebookRule) Generate(params map[string]interface{}) (string, []byte,
 	return hostname, paramsJSON, nil
 }
 
-// @Summary			Generate hostname for category "notebook"
+// @Summary		Generate hostname for category "notebook"
-// @Description		Generates a hostname for a notebook based on dynamic rules.
+// @Description	Generates a hostname for a notebook based on dynamic rules.
 // @ID				insert-notebook-hostname
 // @Accept			json
-// @Produce			json
+// @Produce		json
 // @Tags			Generating Hostnames
 // @Param			body	body		NotebookRuleInput	true	"Input data to generate hostname"
-// @Success			200		{string}	string				"Hostname"
+// @Success		200			{object}	models.SimpleHostnameResponse	"Hostname"
 // @Router			/api/notebook [post]
 func (nr *NotebookRule) Insert(category string, hostname string, paramsJSON []byte) error {
 	return nr.baseInsert(category, hostname, paramsJSON)
 }
 
-// @Summary			Update hostname for category "notebook"
+// @Summary		Update hostname for category "notebook"
-// @Description		Generates a new hostname for a notebook based on dynamic rules.
+// @Description	Generates a new hostname for a notebook based on dynamic rules.
 // @ID				update-notebook-hostname
 // @Accept			json
-// @Produce			json
+// @Produce		json
 // @Tags			Generating Hostnames
 // @Param			body	body		NotebookRuleInput	true	"Input data to generate hostname"
-// @Success			200		{string}	string				"Hostname"
+// @Success		200			{object}	models.SimpleHostnameResponse	"Hostname"
 // @Router			/api/notebook [put]
 func (nr *NotebookRule) Update(category string, oldhostname string, hostname string, paramsJSON []byte) error {
 	return nr.baseUpdate(category, oldhostname, hostname, paramsJSON)