Merge pull request #68 from samueldasilvadev/creating-auto-generated-docs

chore: creating docs generator

Author: samueldasilvadev

.air.toml

@@ -13,7 +13,7 @@ tmp_dir = "tmp"
   exclude_unchanged = true
   follow_symlink = false
   full_bin = ""
-  include_dir = []
+  include_dir = ["docs"]
   include_ext = ["go", "env"]
   kill_delay = "0s"
   log = "build-errors.log"

Makefile

@@ -0,0 +1,2 @@
+update_docs:
+	docker exec zord-http swag init -g ./cmd/http/main.go --parseDependency --propertyStrategy pascalcase

cmd/http/handlers/dummy.go

@@ -4,6 +4,7 @@ import (
 	"go-skeleton/internal/application/domain/dummy"
 	"go-skeleton/internal/application/providers/filters"
 	"go-skeleton/internal/application/providers/pagination"
+	_ "go-skeleton/internal/application/services"
 	dummyCreate "go-skeleton/internal/application/services/dummy/CREATE"
 	dummyDelete "go-skeleton/internal/application/services/dummy/DELETE"
 	dummyEdit "go-skeleton/internal/application/services/dummy/EDIT"
@@ -36,13 +37,23 @@ func NewDummyHandlers(reg *registry.Registry) *DummyHandlers {
 	}
 }
 
+// HandleGetDummy Get Dummy
+// @Summary      Get a Dummy
+// @Tags         Dummy
+// @Accept       json
+// @Produce      json
+// @Param        dummy_id path string true "Dummy ID"
+// @Success      200  {object}  dummyGet.Response
+// @Failure      400  {object}  services.Error
+// @Failure      404  {object}  services.Error
+// @Failure      500  {object}  services.Error
+// @Router       /dummy/{dummy_id} [get]
 func (hs *DummyHandlers) HandleGetDummy(context echo.Context) error {
 	s := dummyGet.NewService(hs.logger, hs.DummyRepository)
 	data := new(dummyGet.Data)
 
 	if errors := context.Bind(data); errors != nil {
-		s.CustomError(http.StatusBadRequest, errors)
-		return context.JSON(s.Error.Status, s.Error)
+		return context.JSON(422, errors)
 	}
 
 	s.Execute(
@@ -56,13 +67,23 @@ func (hs *DummyHandlers) HandleGetDummy(context echo.Context) error {
 	return context.JSON(http.StatusOK, response)
 }
 
+// HandleCreateDummy Create Dummy
+// @Summary      Create Dummy
+// @Tags         Dummy
+// @Accept       json
+// @Produce      json
+// @Param        request body dummyCreate.Data true "body model"
+// @Success      200  {object}  dummyCreate.Response
+// @Failure      400  {object}  services.Error
+// @Failure      404  {object}  services.Error
+// @Failure      500  {object}  services.Error
+// @Router       /dummy [post]
 func (hs *DummyHandlers) HandleCreateDummy(context echo.Context) error {
 	s := dummyCreate.NewService(hs.logger, hs.DummyRepository, hs.idCreator)
 	data := new(dummyCreate.Data)
 
 	if errors := context.Bind(data); errors != nil {
-		s.CustomError(http.StatusBadRequest, errors)
-		return context.JSON(s.Error.Status, s.Error)
+		return context.JSON(http.StatusBadRequest, errors)
 	}
 
 	s.Execute(
@@ -76,17 +97,29 @@ func (hs *DummyHandlers) HandleCreateDummy(context echo.Context) error {
 	return context.JSON(http.StatusCreated, response)
 }
 
+// HandleEditDummy Edit Dummy
+// @Summary      Edit Dummy
+// @Tags         Dummy
+// @Accept       json
+// @Produce      json
+// @Param        dummy_id path string true "Dummy ID"
+// @Param        request body dummyEdit.Data true "body model"
+// @Success      200  {object}  dummyEdit.Response
+// @Failure      400  {object}  services.Error
+// @Failure      404  {object}  services.Error
+// @Failure      500  {object}  services.Error
+// @Router       /dummy/{dummy_id} [put]
 func (hs *DummyHandlers) HandleEditDummy(context echo.Context) error {
 	s := dummyEdit.NewService(hs.logger, hs.DummyRepository)
 	data := new(dummyEdit.Data)
 
+	id := context.Param("id")
 	if errors := context.Bind(data); errors != nil {
-		s.CustomError(http.StatusBadRequest, errors)
-		return context.JSON(s.Error.Status, s.Error)
+		return context.JSON(http.StatusBadRequest, errors)
 	}
 
 	s.Execute(
-		dummyEdit.NewRequest(data, hs.validator),
+		dummyEdit.NewRequest(id, data, hs.validator),
 	)
 
 	response, err := s.GetResponse()
@@ -96,6 +129,19 @@ func (hs *DummyHandlers) HandleEditDummy(context echo.Context) error {
 	return context.JSON(http.StatusOK, response)
 }
 
+// HandleListDummy List Dummy
+// @Summary      List Dummy
+// @Tags         Dummy
+// @Accept       json
+// @Produce      json
+// @Param        page  query   int  true  "valid int"
+// @Param        name  query   string  false  "value example: eql|lik,value"
+// @Param        email  query   string  false  "value example: lik,value"
+// @Success      200  {object}  dummyList.Response
+// @Failure      400  {object}  services.Error
+// @Failure      404  {object}  services.Error
+// @Failure      500  {object}  services.Error
+// @Router       /dummy [get]
 func (hs *DummyHandlers) HandleListDummy(context echo.Context) error {
 	s := dummyList.NewService(
 		hs.logger,
@@ -111,8 +157,7 @@ func (hs *DummyHandlers) HandleListDummy(context echo.Context) error {
 		BindErrors()
 
 	if bindErr != nil {
-		s.CustomError(http.StatusBadRequest, bindErr)
-		return context.JSON(http.StatusBadRequest, s.Error)
+		return context.JSON(http.StatusBadRequest, bindErr)
 	}
 
 	f := filters.NewFilters()
@@ -128,13 +173,23 @@ func (hs *DummyHandlers) HandleListDummy(context echo.Context) error {
 	return context.JSON(http.StatusOK, response)
 }
 
+// HandleDeleteDummy Delete Dummy
+// @Summary      Delete Dummy
+// @Tags         Dummy
+// @Accept       json
+// @Produce      json
+// @Param        dummy_id path string true "Dummy ID"
+// @Success      200  {object}  dummyDelete.Response
+// @Failure      400  {object}  services.Error
+// @Failure      404  {object}  services.Error
+// @Failure      500  {object}  services.Error
+// @Router       /dummy/{dummy_id} [delete]
 func (hs *DummyHandlers) HandleDeleteDummy(context echo.Context) error {
 	s := dummyDelete.NewService(hs.logger, hs.DummyRepository)
 	data := new(dummyDelete.Data)
 
 	if errors := context.Bind(data); errors != nil {
-		s.CustomError(http.StatusBadRequest, errors)
-		return context.JSON(s.Error.Status, s.Error)
+		return context.JSON(http.StatusBadRequest, errors)
 	}
 
 	s.Execute(

cmd/http/main.go

@@ -12,6 +12,9 @@ var (
 	reg *registry.Registry
 )
 
+// @title Swagger Zord API
+// @version 1.0
+// @description This is the Zord backend server.
 func main() {
 	cmd.Setup()
 	serverInstance := server.NewServer(cmd.Reg, cmd.ApiPrefix)

cmd/http/routes/declarable.go

@@ -17,7 +17,7 @@ func GetRoutes(reg *registry.Registry) map[string]Declarable {
 	//{{codeGen1}}
 	routes := map[string]Declarable{
 		"health": health,
-		"dummy":  dummyListRoutes,
+		"dummy": dummyListRoutes,
 		//{{codeGen2}}
 	}
 	return routes

cmd/http/routes/dummy.go

@@ -18,12 +18,12 @@ func NewDummyRoutes(reg *registry.Registry) *DummyRoutes {
 	}
 }
 
-func (hs *DummyRoutes) DeclarePublicRoutes(server *echo.Group, apiPrefix string) {}
-
 func (hs *DummyRoutes) DeclarePrivateRoutes(server *echo.Group, apiPrefix string) {
 	server.GET(apiPrefix+"/dummy", hs.hand.HandleListDummy)
 	server.GET(apiPrefix+"/dummy/:id", hs.hand.HandleGetDummy)
 	server.POST(apiPrefix+"/dummy", hs.hand.HandleCreateDummy)
 	server.PUT(apiPrefix+"/dummy/:id", hs.hand.HandleEditDummy)
 	server.DELETE(apiPrefix+"/dummy/:id", hs.hand.HandleDeleteDummy)
 }
+
+func (hs *DummyRoutes) DeclarePublicRoutes(server *echo.Group, apiPrefix string) {}

cmd/http/server/server.go

@@ -2,7 +2,9 @@ package server
 
 import (
 	"fmt"
+	echoSwagger "github.com/swaggo/echo-swagger"
 	"go-skeleton/cmd/http/routes"
+	"go-skeleton/docs"
 	"go-skeleton/pkg/config"
 	"go-skeleton/pkg/logger"
 	"go-skeleton/pkg/registry"
@@ -33,6 +35,12 @@ func (hs *Server) Start() {
 	server.HideBanner = true
 	server.HidePort = true
 
+	if hs.config.ReadConfig("ENVIRONMENT") == "development" {
+		docs.SwaggerInfo.Host = "localhost:" + hs.config.ReadConfig("HTTP_PORT")
+		docs.SwaggerInfo.BasePath = "/" + hs.config.ReadConfig("API_PREFIX")
+		server.GET("/swagger/*", echoSwagger.WrapHandler)
+	}
+
 	server.Use(middleware.Recover())
 
 	public := server.Group("")

docker-compose.yml compose.ymldocker-compose.yml renamed to compose.yml

@@ -1,4 +1,3 @@
-version: '3.7'
 services:
   zord-http:
     build:
@@ -8,7 +7,7 @@ services:
     env_file:
       - .env
     ports:
-      - "9005:9000"
+      - "9000:9000"
     command: air http
     depends_on:
       mysql:

docker/dev/Dockerfile

@@ -11,4 +11,6 @@ ENV ATLAS_VERSION=v0.20.1-7793896-canary
 RUN curl -sSf https://atlasgo.sh | sh
 
 RUN go mod download
-RUN go install github.com/cosmtrek/air@latest
+RUN go install github.com/air-verse/air@latest
+RUN go install github.com/swaggo/swag/cmd/swag@latest
+RUN apk add build-base