From 607682884ce76d3ffad1b9fed96f0ccb66b2036e Mon Sep 17 00:00:00 2001 From: Florian Beisel Date: Thu, 18 Jan 2024 00:09:26 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Create=20missing=20models=20for?= =?UTF-8?q?=20API=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/handlers.go | 58 +++++++++++++++++++++++----------------------- auth/handlers.go | 11 +++++---- models/error.go | 5 ++++ models/hostname.go | 17 ++++++++++---- models/login.go | 10 ++++++-- rules/notebook.go | 16 ++++++------- 6 files changed, 68 insertions(+), 49 deletions(-) create mode 100644 models/error.go diff --git a/api/handlers.go b/api/handlers.go index 64ca99a..d4ee8ff 100644 --- a/api/handlers.go +++ b/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 -// @Description List all details for a given category -// @ID delete-hostnames-by-category-and-name -// @Produce json -// @Param category path string true "Category of the hostname" -// @Param hostname path string true "Hostname to delete" -// @Success 200 {json} json "Hostname" -// @Security Bearer -// @Tags Manipulate existing Hostnames -// @Router /{category}/{hostname} [delete] +// @Summary Delete a hostname from the database +// @Description List all details for a given category +// @ID delete-hostnames-by-category-and-name +// @Produce json +// @Param category path string true "Category of the hostname" +// @Param hostname path string true "Hostname to delete" +// @Success 200 {object} models.SimpleHostnameResponse "Hostname" +// @Security Bearer +// @Tags Manipulate existing Hostnames +// @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 -// @Description List all details for a given category -// @ID list-hostnames-by-category -// @Produce json -// @Param category path string true "Category of the hostname" -// @Success 200 {json} json "Hostname" -// @Security Bearer -// @Tags Querying Hostnames -// @Router /{category} [get] +// @Summary Return a list of hosts and their details filtered by category +// @Description List all details for a given category +// @ID list-hostnames-by-category +// @Produce json +// @Param category path string true "Category of the hostname" +// @Success 200 {array} models.Hostname "An array of responses" +// @Security Bearer +// @Tags Querying Hostnames +// @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 -// @Description Return details for a single hostname identified by its category -// @ID get-hostname-by-category-and-name -// @Produce json -// @Param category path string true "Category of the hostname" -// @Param hostname path string true "Category of the hostname" -// @Security Bearer -// @Success 200 {json} json "Hostname" -// @Tags Querying Hostnames -// @Router /{category}/{hostname} [get] +// @Summary Return a single hostname by Category and Name +// @Description Return details for a single hostname identified by its category +// @ID get-hostname-by-category-and-name +// @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 +// @Tags Querying Hostnames +// @Router /{category}/{hostname} [get] func GetHostnameByCategoryAndName(c *gin.Context) { category := c.Param("category") hostname := c.Param("hostname") diff --git a/auth/handlers.go b/auth/handlers.go index 2da932e..5aaafb3 100644 --- a/auth/handlers.go +++ b/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" -// @Failure 400 {object} map[string]string "Invalid request body" -// @Failure 401 {object} map[string]string "Invalid login credentials" -// @Failure 500 {object} map[string]string "Internal server error" +// @Success 200 {object} models.TokenResponse "Successfully authenticated, JWT token returned" +// @Failure 400 {object} models.ErrorResponse "Invalid request body" +// @Failure 401 {object} models.ErrorResponse "Invalid login credentials" +// @Failure 500 {object} models.ErrorResponse "Internal server error" // @Router /login [post] func LoginHandler(c *gin.Context) { var creds models.LoginCredentials diff --git a/models/error.go b/models/error.go new file mode 100644 index 0000000..c44e8c6 --- /dev/null +++ b/models/error.go @@ -0,0 +1,5 @@ +package models + +type ErrorResponse struct { + Error string `json:"error"` +} diff --git a/models/hostname.go b/models/hostname.go index b360f10..8affc69 100644 --- a/models/hostname.go +++ b/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 - Category string `json:"category"` // Category / Rule that was used when generating the hostname - Hostname string `json:"hostname"` // Generated hostname - Parameters map[string]interface{} `json:"parameters"` // Parameter object of rule specific attributes - CreatedAt time.Time `json:"created_at"` // Creation Time of the entry + ID int `json:"Id" example:"25"` // Internal ID of the Hostname within the database + Category string `json:"Category" example:"notebook"` // Category / Rule that was used when generating the hostname + Hostname string `json:"Hostname" example:"ISEHENNB0009"` // Generated hostname + Parameters map[string]interface{} `json:"Parameters"` // Parameter object of rule specific attributes, see rule.* models + 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 } diff --git a/models/login.go b/models/login.go index 45ce501..3d23837 100644 --- a/models/login.go +++ b/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"` - Password string `json:"password"` + Username string `json:"Username"` + Password string `json:"Password"` +} + +// JWT Token Response Model +// @Description Model returned after successful login +type TokenResponse struct { + Token string `json:"token"` } diff --git a/rules/notebook.go b/rules/notebook.go index e681561..a145c8b 100644 --- a/rules/notebook.go +++ b/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" -// @Description Generates a hostname for a notebook based on dynamic rules. +// @Summary Generate hostname for category "notebook" +// @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" -// @Description Generates a new hostname for a notebook based on dynamic rules. +// @Summary Update hostname for category "notebook" +// @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)