florian
/
hostname-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 Create missing models for API documentation

This commit is contained in:
Florian Beisel 2024-01-18 00:09:26 +01:00
parent e0190f4bb5
commit 607682884c
Signed by: florian
GPG Key ID: 79ECA2E54996FF4D
6 changed files with 68 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
api/handlers.go
View File

@ -68,16 +68,16 @@ func CreateOrUpdateHostname(c *gin.Context, isUpdate bool) {
c.JSON(http.StatusOK, gin.H{"hostname": hostname}) 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) { func DeleteHostname(c *gin.Context) {
category := c.Param("category") category := c.Param("category")
hostname := c.Param("hostname") hostname := c.Param("hostname")
@ -90,15 +90,15 @@ func DeleteHostname(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"hostname": hostname}) 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) { func ListHostnamesByCategory(c *gin.Context) {
category := c.Param("category") category := c.Param("category")
@ -114,16 +114,16 @@ func ListHostnamesByCategory(c *gin.Context) {
c.JSON(http.StatusOK, hostnames) 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) { func GetHostnameByCategoryAndName(c *gin.Context) {
category := c.Param("category") category := c.Param("category")
hostname := c.Param("hostname") hostname := c.Param("hostname")

11
auth/handlers.go
View File

@ -11,17 +11,18 @@ import (
"github.com/gin-gonic/gin" "github.com/gin-gonic/gin"
) )
// LoginHandler godoc // LoginHandler godoc
//
// @Summary User login // @Summary User login
// @Description Authenticate user and return JWT token // @Description Authenticate user and return JWT token
// @Tags Authentication // @Tags Authentication
// @Accept json // @Accept json
// @Produce json // @Produce json
// @Param loginCredentials body models.LoginCredentials true "Login Credentials" // @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] // @Router /login [post]
func LoginHandler(c *gin.Context) { func LoginHandler(c *gin.Context) {
var creds models.LoginCredentials var creds models.LoginCredentials

5
models/error.go Normal file
View File

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

17
models/hostname.go
View File

@ -6,9 +6,16 @@ import "time"
// @Description Model of the Hostname as it // @Description Model of the Hostname as it
// @Description is represented in the database // @Description is represented in the database
type Hostname struct { 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
} }

10
models/login.go
View File

@ -4,6 +4,12 @@ package models
// @Description User account information used in the login process // @Description User account information used in the login process
// @Description with Username and password // @Description with Username and password
type LoginCredentials struct { 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"`
} }

16
rules/notebook.go
View File

@ -66,27 +66,27 @@ func (nr *NotebookRule) Generate(params map[string]interface{}) (string, []byte,
return hostname, paramsJSON, nil 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 // @ID insert-notebook-hostname
// @Accept json // @Accept json
// @Produce json // @Produce json
// @Tags Generating Hostnames // @Tags Generating Hostnames
// @Param body body NotebookRuleInput true "Input data to generate hostname" // @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] // @Router /api/notebook [post]
func (nr *NotebookRule) Insert(category string, hostname string, paramsJSON []byte) error { func (nr *NotebookRule) Insert(category string, hostname string, paramsJSON []byte) error {
return nr.baseInsert(category, hostname, paramsJSON) 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 // @ID update-notebook-hostname
// @Accept json // @Accept json
// @Produce json // @Produce json
// @Tags Generating Hostnames // @Tags Generating Hostnames
// @Param body body NotebookRuleInput true "Input data to generate hostname" // @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] // @Router /api/notebook [put]
func (nr *NotebookRule) Update(category string, oldhostname string, hostname string, paramsJSON []byte) error { func (nr *NotebookRule) Update(category string, oldhostname string, hostname string, paramsJSON []byte) error {
return nr.baseUpdate(category, oldhostname, hostname, paramsJSON) return nr.baseUpdate(category, oldhostname, hostname, paramsJSON)