Lots of fiddling with swagger annotations in user related handlers

backend/internal/handlers/users/ListAllUsers.go

@@ -7,16 +7,17 @@ import (
 	"github.com/gofiber/fiber/v2/log"
 )
 
-// ListAllUsers is a handler that returns a list of all users in the application database
 //	@Summary		ListsAllUsers
 //	@Description	lists all users
 //	@Tags			User
-// @Accept			json
+//	@Produce		json
-// @Produce		plain
+//	@Security		JWT
-// @Success		200	{json}		json	"Successfully signed token for user"
+//	@Success		200	{array}		string	"Successfully returned all users"
 //	@Failure		401	{string}	string	"Unauthorized"
 //	@Failure		500	{string}	string	"Internal server error"
 //	@Router			/users/all [get]
+//
+// ListAllUsers returns a list of all users in the application database
 func ListAllUsers(c *fiber.Ctx) error {
 	// Get all users from the database
 	users, err := db.GetDb(c).GetAllUsersApplication()

backend/internal/handlers/users/Login.go

@@ -10,18 +10,19 @@ import (
 	"github.com/golang-jwt/jwt/v5"
 )
 
-// Login is a simple login handler that returns a JWT token
+//	@Summary		Login
-// @Summary		login
+//	@Description	Logs in a user and returns a JWT token
-// @Description	logs the user in and returns a jwt token
+//	@Tags			Auth
-// @Tags			User
 //	@Accept			json
-// @Param			NewUser	body	types.NewUser	true	"login info"
+//	@Produce		json
-// @Produce		plain
+//	@Param			body	body		types.NewUser	true	"User credentials"
-// @Success		200	Token		types.Token	"Successfully signed token for user"
+//	@Success		200		{object}	types.Token		"JWT token"
 //	@Failure		400		{string}	string			"Bad request"
 //	@Failure		401		{string}	string			"Unauthorized"
 //	@Failure		500		{string}	string			"Internal server error"
 //	@Router			/login [post]
+//
+// Login logs in a user and returns a JWT token
 func Login(c *fiber.Ctx) error {
 	// The body type is identical to a NewUser
 

backend/internal/handlers/users/LoginRenew.go

@@ -9,34 +9,40 @@ import (
 	"github.com/golang-jwt/jwt/v5"
 )
 
-// LoginRenew is a simple handler that renews the token
 //	@Summary		LoginRenews
-// @Description	renews the users token
+//	@Description	Renews the users token.
-// @Security		bererToken
+//	@Tags			Auth
-// @Tags			User
+//	@Produce		json
-// @Accept			json
+//	@Security		JWT
-// @Produce		plain
+//	@Success		200	{object}	types.Token	"Successfully signed token for user"
-// @Success		200	Token		types.Token	"Successfully signed token for user"
 //	@Failure		401	{string}	string		"Unauthorized"
 //	@Failure		500	{string}	string		"Internal server error"
-// @Router			/loginerenew [post]
+//	@Router			/loginrenew [post]
+//
+// LoginRenew renews the users token
 func LoginRenew(c *fiber.Ctx) error {
 	user := c.Locals("user").(*jwt.Token)
 
 	log.Info("Renewing token for user:", user.Claims.(jwt.MapClaims)["name"])
 
+	// Renewing the token means we trust whatever is already in the token
 	claims := user.Claims.(jwt.MapClaims)
+
+	// 72 hour expiration time
 	claims["exp"] = time.Now().Add(time.Hour * 72).Unix()
-	renewed := jwt.MapClaims{
+
+	// Create token with old claims, but new expiration time
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
 		"name":  claims["name"],
 		"admin": claims["admin"],
 		"exp":   claims["exp"],
-	}
+	})
-	token := jwt.NewWithClaims(jwt.SigningMethodHS256, renewed)
+
+	// Sign it with top secret key
 	t, err := token.SignedString([]byte("secret"))
 	if err != nil {
 		log.Warn("Error signing token")
-		return c.SendStatus(fiber.StatusInternalServerError)
+		return c.SendStatus(fiber.StatusInternalServerError) // 500
 	}
 
 	log.Info("Successfully renewed token for user:", user.Claims.(jwt.MapClaims)["name"])

backend/internal/handlers/users/PromoteToAdmin.go

@@ -9,16 +9,19 @@ import (
 )
 
 //	@Summary		PromoteToAdmin
-// @Description	promote chosen user to admin
+//	@Description	Promote chosen user to site admin
 //	@Tags			User
 //	@Accept			json
 //	@Produce		plain
+//	@Security		JWT
 //	@Param			NewUser	body		types.NewUser	true	"user info"
-// @Success		200		{json}		json			"Successfully promoted user"
+//	@Success		200		{object}	types.Token		"Successfully promoted user"
 //	@Failure		400		{string}	string			"Bad request"
 //	@Failure		401		{string}	string			"Unauthorized"
 //	@Failure		500		{string}	string			"Internal server error"
 //	@Router			/promoteToAdmin [post]
+//
+// PromoteToAdmin promotes a user to a site admin
 func PromoteToAdmin(c *fiber.Ctx) error {
 	// Extract the username from the request body
 	var newUser types.NewUser

backend/internal/handlers/users/Register.go

@@ -8,11 +8,9 @@ import (
 	"github.com/gofiber/fiber/v2/log"
 )
 
-// Register is a simple handler that registers a new user
-//
 //	@Summary		Register
 //	@Description	Register a new user
-//	@Tags			User
+//	@Tags			Auth
 //	@Accept			json
 //	@Produce		plain
 //	@Param			NewUser	body		types.NewUser	true	"User to register"
@@ -20,6 +18,8 @@ import (
 //	@Failure		400		{string}	string			"Bad request"
 //	@Failure		500		{string}	string			"Internal server error"
 //	@Router			/register [post]
+//
+// Register is a simple handler that registers a new user
 func Register(c *fiber.Ctx) error {
 	u := new(types.NewUser)
 	if err := c.BodyParser(u); err != nil {

backend/internal/handlers/users/UserDelete.go

@@ -8,19 +8,19 @@ import (
 	"github.com/golang-jwt/jwt/v5"
 )
 
-// This path should obviously be protected in the future
-// UserDelete deletes a user from the database
-//
 //	@Summary		UserDelete
 //	@Description	UserDelete deletes a user from the database
 //	@Tags			User
 //	@Accept			json
 //	@Produce		plain
+//	@Security		JWT
 //	@Success		200	{string}	string	"User deleted"
 //	@Failure		403	{string}	string	"You can only delete yourself"
 //	@Failure		500	{string}	string	"Internal server error"
 //	@Failure		401	{string}	string	"Unauthorized"
 //	@Router			/userdelete/{username} [delete]
+//
+// UserDelete deletes a user from the database
 func UserDelete(c *fiber.Ctx) error {
 	// Read from path parameters
 	username := c.Params("username")

backend/internal/types/users.go

@@ -18,8 +18,8 @@ func (u *User) ToPublicUser() (*PublicUser, error) {
 
 // Should be used when registering, for example
 type NewUser struct {
-	Username string `json:"username"`
+	Username string `json:"username" example:"username123"`
-	Password string `json:"password"`
+	Password string `json:"password" example:"password123"`
 }
 
 // PublicUser represents a user that is safe to send over the API (no password)