📝 Create missing models for API documentation

api/handlers.go

@@ -74,7 +74,7 @@ func CreateOrUpdateHostname(c *gin.Context, isUpdate bool) {
 //	@Produce		json
 //	@Param			category	path		string							true	"Category of the hostname"
 //	@Param			hostname	path		string							true	"Hostname to delete"
-// @Success		200			{json}	json	"Hostname"
+//	@Success		200			{object}	models.SimpleHostnameResponse	"Hostname"
 //	@Security		Bearer
 //	@Tags			Manipulate existing Hostnames
 //	@Router			/{category}/{hostname} [delete]
@@ -95,7 +95,7 @@ func DeleteHostname(c *gin.Context) {
 //	@ID				list-hostnames-by-category
 //	@Produce		json
 //	@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
 //	@Tags			Querying Hostnames
 //	@Router			/{category} [get]
@@ -120,8 +120,8 @@ func ListHostnamesByCategory(c *gin.Context) {
 //	@Produce		json
 //	@Param			category	path		string			true	"Category of the hostname"
 //	@Param			hostname	path		string			true	"Category of the hostname"
+//	@Success		200			{object}	models.Hostname	"A single response object"
 //	@Security		Bearer
-// @Success		200	{json}	json	"Hostname"
 //	@Tags			Querying Hostnames
 //	@Router			/{category}/{hostname} [get]
 func GetHostnameByCategoryAndName(c *gin.Context) {

auth/handlers.go

@@ -12,16 +12,17 @@ import (
 )
 
 //	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

@@ -73,7 +73,7 @@ func (nr *NotebookRule) Generate(params map[string]interface{}) (string, []byte,
 // @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)
@@ -86,7 +86,7 @@ func (nr *NotebookRule) Insert(category string, hostname string, paramsJSON []by
 // @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)