feat: added swaggo support

cmd/api-server/main.go

@@ -19,6 +19,23 @@ import (
 	"github.com/robindittmar/dttmr-api/internal/telemetry"
 )
 
+// @title dttmr-api
+// @version 0.1.0
+// @description API documentation for dttmr-api service.
+// @termsOfService http://swagger.io/terms/
+
+// @contact.name Robin Dittmar
+// @contact.email robindittmar@gmail.com
+
+// @license.name MIT
+// @license.url https://opensource.org/licenses/MIT
+
+// @host localhost:8080
+// @BasePath /api/v1
+
+// @securityDefinitions.apikey Bearer Token
+// @in Header
+// @name Authorization
 func main() {
 	serviceName := "dttmr-api"
 	serviceVersion := "0.1.0"

internal/api/handler/auth.go

@@ -17,6 +17,18 @@ func NewAuthHandler(authService *domain.AuthService) *AuthHandler {
 	return &AuthHandler{AuthService: authService}
 }
 
+// Login handles the login of a user
+//
+// @Summary Login route
+// @Description User authorization and token issuing
+// @Tags Authorization
+// @Accept json
+// @Produce json
+// @Param payload body request.LoginPayload true "Login payload"
+// @Success 200 {object} domain.AuthToken
+// @Error 400 {object} response.ErrorResponse "failed to decode request body"
+// @Error 500 {object} response.ErrorResponse "failed to login"
+// @Router /api/v1/login [post]
 func (h *AuthHandler) Login(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

internal/api/handler/default.go

@@ -17,6 +17,15 @@ type apiResponse struct {
 	Form       map[string]string `json:"form"`
 }
 
+// DefaultHandler handles the default route
+//
+// @Summary Default route handler
+// @Description Default route handler
+// @Tags
+// @Accept json
+// @Produce json
+// @Success 200 {object} apiResponse
+// @Router /api/v1/ [get]
 func DefaultHandler(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

internal/api/handler/health.go

@@ -10,6 +10,15 @@ type healthResponse struct {
 	Status string `json:"status"`
 }
 
+// HealthHandler handles the health check route
+//
+// @Summary Health check
+// @Description Health check reports the status of the API
+// @Tags Health
+// @Accept json
+// @Produce json
+// @Success 200 {object} healthResponse
+// @Router /health [get]
 func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

internal/api/handler/list.go

@@ -17,6 +17,18 @@ func NewListHandler(listService *domain.ListService) *ListHandler {
 	return &ListHandler{ListService: listService}
 }
 
+// CreateList handles the creation of a list
+//
+// @Summary Create list route
+// @Description Create a list and associate user(s) to it
+// @Tags List
+// @Accept json
+// @Produce json
+// @Param payload body request.CreateListPayload true "Create list payload"
+// @Success 201 {object} domain.List
+// @Error 400 {object} response.ErrorResponse "failed to decode request body"
+// @Error 500 {object} response.ErrorResponse "failed to create list"
+// @Router /api/v1/list [post]
 func (h *ListHandler) CreateList(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

internal/api/handler/user.go

@@ -17,6 +17,18 @@ func NewUserHandler(userService *domain.UserService) *UserHandler {
 	return &UserHandler{UserService: userService}
 }
 
+// CreateUser handles the creation of a user
+//
+// @Summary Create user route
+// @Description Create a user
+// @Tags User
+// @Accept json
+// @Produce json
+// @Param payload body request.CreateUserPayload true "Create user payload"
+// @Success 201 {object} domain.User
+// @Error 400 {object} response.ErrorResponse "failed to decode request body"
+// @Error 500 {object} response.ErrorResponse "failed to create user"
+// @Router /api/v1/user [post]
 func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 

internal/api/router/router.go

@@ -30,14 +30,17 @@ func NewMux(cfg Config) http.Handler {
 
 	protected := middleware.WithJWT(authService)
 
+	apiMux := http.NewServeMux()
+	apiMux.HandleFunc("/", handler.DefaultHandler)
+	apiMux.HandleFunc("POST /login", authHandler.Login)
+
+	apiMux.Handle("POST /users", protected(userHandler.CreateUser))
+
+	apiMux.Handle("POST /lists", protected(listHandler.CreateList))
+
 	mux := http.NewServeMux()
-	mux.HandleFunc("/", handler.DefaultHandler)
 	mux.HandleFunc("GET /health", handler.HealthHandler)
-	mux.HandleFunc("POST /login", authHandler.Login)
+	mux.Handle("/api/v1/", http.StripPrefix("/api/v1", apiMux))
-
-	mux.Handle("POST /users", protected(userHandler.CreateUser))
-
-	mux.Handle("POST /lists", protected(listHandler.CreateList))
 
 	var httpHandler http.Handler = mux
 	httpHandler = middleware.WithMaxBytes(1024 * 64)(httpHandler)