Refactor User Management API and Update Documentation

- Changed API tags from "Admin-Users" to "Admin-Authorization" for better clarity in user management endpoints.
- Removed unused endpoints for retrieving users by company ID and role, streamlining the user management functionality.
- Updated user entity and forms to reflect new example values for improved clarity in API documentation.
- Enhanced pagination handling in user listing responses, ensuring consistent metadata structure.
- Updated API documentation to reflect changes in endpoint structure and response formats, improving clarity for API consumers.

pkg/response/response.go

@@ -2,6 +2,7 @@ package response
 
 import (
 	"net/http"
+	"strconv"
 
 	"github.com/asaskevich/govalidator"
 	"github.com/labstack/echo/v4"
@@ -32,6 +33,13 @@ type Meta struct {
 	Pages  int `json:"pages"`
 }
 
+type Pagination struct {
+	Limit     int    `query:"limit" valid:"optional,range(1|100)" default:"20"`
+	Offset    int    `query:"offset" valid:"optional,min(0)" default:"0"`
+	SortBy    string `query:"sort_by" valid:"optional"`
+	SortOrder string `query:"sort_order" valid:"optional,in(asc|desc)"`
+}
+
 // Success returns a successful response
 func Success(c echo.Context, data interface{}, message string) error {
 	return c.JSON(http.StatusOK, APIResponse{
@@ -171,3 +179,34 @@ func Parse[T any](c echo.Context) (*T, error) {
 
 	return &form, nil
 }
+
+func NewPagination(c echo.Context) *Pagination {
+	limit, err := strconv.Atoi(c.QueryParam("limit"))
+	if err != nil {
+		limit = 20
+	}
+
+	offset, err := strconv.Atoi(c.QueryParam("offset"))
+	if err != nil {
+		offset = 0
+	}
+
+	return &Pagination{
+		Limit:     limit,
+		Offset:    offset,
+		SortBy:    c.QueryParam("sort_by"),
+		SortOrder: c.QueryParam("sort_order"),
+	}
+}
+
+// Pagination calculates pagination metadata
+func (p *Pagination) Response(total int64) *Meta {
+	pages := (total + int64(p.Limit) - 1) / int64(p.Limit)
+	return &Meta{
+		Total:  int(total),
+		Limit:  p.Limit,
+		Offset: p.Offset,
+		Page:   int(p.Offset/p.Limit) + 1,
+		Pages:  int(pages),
+	}
+}