Issue 119 - Estudar e implementar swagger na aplicação

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Diretrizes de Contribuição para o Repositório da PetDex
+# 1. Diretrizes de Contribuição para o Repositório da PetDex
 
 Bem-vindo à PetDex! Agradecemos pelo seu interesse em contribuir para este projeto open source. Suas contribuições são fundamentais para o sucesso e a melhoria contínua deste projeto. Antes de começar, por favor, leia e siga estas diretrizes para garantir um processo de contribuição harmonioso e eficaz.
 
@@ -74,3 +74,43 @@ Os arquivos .sql deverão ser criados com o comando abaixo:
 Ao executar o comando, serão criados dois arquivos na pasta /migrations com sufixos `.up` e `.down`. Os arquivos `.up` representam as alterações desejadas que serão aplicados no banco de dados, enquantos os arquivos `.down`, representa a ação de rollback referente ao que foi executado no arquivos `.up` de mesma versão.
 
 Obs.: crie os script SQL de forma idempotente e caso o seu script tenha vários comando ou consultas, considere colocar isso em uma transação.
+
+# 2. Diretrizes de Documentação da API PetDex-Backend com Swag 
+
+Swag, é o pacote responsável pela geração automática da documentação API RESTful. O mesmo documenta códigos em Go com Swagger 2.0. 
+
+## Sumário
+
+1. [Dependências](#dependências)
+
+2. [Nova documentação](#executando-o-Swago)
+
+3. [Acesso](#acessando-documentação)
+
+### Dependências
+
+Para habilitar a geração automática de documentação via Swag, é necessário a sua instalação. Execute o comando a seguir para disponibilizar os recursos dessa feramenta pré configurados via Makefile.
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@latest
+```
+
+Em caso de dúvidas na instalação e na sintaxe da documentação, consulte o repositório oficial da documentação através do link a seguir
+* [swag](https://github.com/swaggo/swag)
+
+Também é necessário ter o GNU Make instalado para executar os comandos definidos em Makefile:
+
+* [Make](https://www.gnu.org/software/make/)
+
+### Executando o Swag
+
+Para gerar a documentação da API, depois documentado o endpoint, execute o comando a seguir:
+
+```bash
+make swag
+```
+Esse comando irá atualizar os arquivos swagger disponíveis no diretório `swagger/`
+
+### Acessando Documentação
+
+A documentação estará disponívei para acesso através da rota `api/swagger/`

Makefile

@@ -20,4 +20,7 @@ migration-up:
 	go run cmd/main.go -up 
 
 lint:
-	docker run --rm -v ./:/app -w /app golangci/golangci-lint:v1.59.1 golangci-lint run -v
+	docker run --rm -v ./:/app -w /app golangci/golangci-lint:v1.59.1 golangci-lint run -v
+
+swag:
+	swag init -g api/main.go -o swagger/

api/controllers/pet.go

@@ -116,6 +116,17 @@ func (cntrl *PetController) ListUserPets(w http.ResponseWriter, r *http.Request)
 	w.WriteHeader(http.StatusOK)
 }
 
+// Add Pet to the database.
+// @Summary Create Pet by petDto
+// @Description Sends the Pet's registration data via the request body for persistence in the database.
+// @Tags Pet
+// @Accept json
+// @Produce json
+// @Param petDto body dto.PetInsertDto true "Pet object information for registration"
+// @Success 201
+// @Failure 400
+// @Failure 500
+// @Router /pets/ [post]
 func (cntrl *PetController) CreatePet(w http.ResponseWriter, r *http.Request) {
 	var petToSave dto.PetInsertDto
 

api/main.go

@@ -13,9 +13,23 @@ import (
 	"pet-dex-backend/v2/pkg/sso"
 	"pet-dex-backend/v2/usecase"
 
+	_ "pet-dex-backend/v2/swagger"
+
 	"github.com/jmoiron/sqlx"
 )
 
+// @title PetDex: Documentação API
+// @version 1.0
+// @description Esta página se destina a documentação da API do projeto PetDex Backend
+
+// @contact.name DevHatt
+// @contact.url https://github.com/devhatt
+
+// @license.name MIT license
+// @license.url https://github.com/devhatt/pet-dex-backend?tab=MIT-1-ov-file#readme
+
+// @host localhost:3000/api
+// @BasePath /
 func main() {
 	envVariables, err := config.LoadEnv(".")
 	if err != nil {

api/routes/routes.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
+	httpSwagger "github.com/swaggo/http-swagger"
 )
 
 type Controllers struct {
@@ -38,7 +39,7 @@ func InitRoutes(controllers Controllers, c *chi.Mux) {
 				r.Get("/", controllers.OngController.List)
 				r.Get("/{ongID}", controllers.OngController.FindByID)
 				r.Patch("/{ongID}", controllers.OngController.Update)
-				r.Delete("{ongID}", controllers.OngController.Delete)
+				r.Delete("/{ongID}", controllers.OngController.Delete)
 			})
 
 			private.Route("/user", func(r chi.Router) {
@@ -57,6 +58,9 @@ func InitRoutes(controllers Controllers, c *chi.Mux) {
 			public.Post("/user/{provider}/login", controllers.UserController.ProviderLogin)
 			public.Post("/user/login", controllers.UserController.Login)
 			public.Get("/pets/", controllers.PetController.ListAllPets)
+			public.Get("/swagger/*", httpSwagger.Handler(
+				httpSwagger.URL("doc.json"), //The url endpoint to API definition
+			))
 		})
 
 	})

entity/dto/pet_insert_dto.go

@@ -14,13 +14,13 @@ var nameRegex = regexp.MustCompile(`^[a-zA-Z0-9\s]+$`)
 var sizeRegex = regexp.MustCompile(`^(small|medium|large|giant)$`)
 
 type PetInsertDto struct {
-	Name         string            `json:"name"`
-	UserID       uniqueEntityId.ID `json:"user_id"`
-	BreedID      uniqueEntityId.ID `json:"breed_id"`
-	AdoptionDate *time.Time        `json:"adoption_date"`
-	Birthdate    *time.Time        `json:"birthdate"`
-	Weight       float64           `json:"weight"`
-	Size         string            `json:"size"`
+	Name         string            `json:"name" example:"Thor"`
+	UserID       uniqueEntityId.ID `json:"user_id" example:"fa1b8ae8-5351-11ef-8f02-0242ac130003"`
+	BreedID      uniqueEntityId.ID `json:"breed_id" example:"0e0b8399-1bf1-4ed5-a2f4-b5789ddf5df0"`
+	AdoptionDate *time.Time        `json:"adoption_date" example:"2008-01-02T15:04:05Z"`
+	Birthdate    *time.Time        `json:"birthdate" example:"2006-01-02T15:04:05Z"`
+	Weight       float64           `json:"weight" example:"4.1"`
+	Size         string            `json:"size" example:"medium"`
 }
 
 func (p *PetInsertDto) Validate() error {

go.mod

@@ -3,16 +3,21 @@ module pet-dex-backend/v2
 go 1.21
 
 require (
+	github.com/go-chi/cors v1.2.1
 	github.com/golang-jwt/jwt v3.2.2+incompatible
 	github.com/golang-migrate/migrate/v4 v4.17.1
 	github.com/google/uuid v1.4.0
+	github.com/huandu/facebook/v2 v2.7.3
 	github.com/jmoiron/sqlx v1.3.5
 	github.com/stretchr/testify v1.9.0
+	github.com/swaggo/http-swagger v1.3.4
+	github.com/swaggo/swag v1.16.3
+	golang.org/x/oauth2 v0.21.0
 )
 
 require (
 	github.com/stretchr/objx v0.5.2 // indirect
-	golang.org/x/crypto v0.21.0
+	golang.org/x/crypto v0.25.0
 )
 
 require (
@@ -25,29 +30,36 @@ require (
 
 require (
 	cloud.google.com/go/compute/metadata v0.3.0 // indirect
+	github.com/KyleBanks/depth v1.2.1 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
-	github.com/go-chi/cors v1.2.1 // indirect
+	github.com/go-openapi/jsonpointer v0.21.0 // indirect
+	github.com/go-openapi/jsonreference v0.21.0 // indirect
+	github.com/go-openapi/spec v0.21.0 // indirect
+	github.com/go-openapi/swag v0.23.0 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
-	github.com/huandu/facebook/v2 v2.7.3 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
-	github.com/markbates/goth v1.80.0 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.1.0 // indirect
+	github.com/rogpeppe/go-internal v1.12.0 // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
 	github.com/spf13/afero v1.11.0 // indirect
 	github.com/spf13/cast v1.6.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
+	github.com/swaggo/files v1.0.1 // indirect
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
-	golang.org/x/oauth2 v0.21.0 // indirect
-	golang.org/x/sys v0.18.0 // indirect
-	golang.org/x/text v0.14.0 // indirect
+	golang.org/x/net v0.27.0 // indirect
+	golang.org/x/sys v0.22.0 // indirect
+	golang.org/x/text v0.16.0 // indirect
+	golang.org/x/tools v0.23.0 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )