Documentação. Documentação. Documentação. Não precisamos falar o quão importante é isso dentro de uma empresa, tenha ela o tamanho que for.
O Swagger é uma excelente ferramenta para realizar esse trabalho em qualquer API REST.
Vocês acreditam ser algo complicado e manual criar essa documentação? Vamos dar uma olhada.
Primeiramente, como o swagger está aí com o papel de documentar nossos métodos REST que estão expostos, vamos trabalhar com ele diretamente na nossa camada de service no adapter http.
Começamos editando o arquivo adapter/http/productservice/create.go
.
// @Summary Create new product
// @Description Create new product
// @Tags product
// @Accept json
// @Produce json
// @Param product body dto.CreateProductRequest true "product"
// @Success 200 {object} domain.Product
// @Router /product [post]
func (service service) Create(response http.ResponseWriter, request *http.Request) {
...
}
Depois o arquivo adapter/http/productservice/fetch.go
.
// @Summary Fetch products with server pagination
// @Description Fetch products with server pagination
// @Tags product
// @Accept json
// @Produce json
// @Param sort query string true "1,2"
// @Param descending query string true "true,false"
// @Param page query integer true "1"
// @Param itemsPerPage query integer true "10"
// @Param search query string false ""
// @Success 200 {object} domain.Pagination
// @Router /product [get]
func (service service) Fetch(response http.ResponseWriter, request *http.Request) {
...
}
E por fim o arquivo adapter/http/main.go
.
// @title Clean GO API Docs
// @version 1.0.0
// @contact.name Vinícius Boscardin
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:port
// @BasePath /
func main() {
...
}
Bom, se nós rodarmos a api agora nada vai acontecer! Vamos botar essas tags para funcionar. Em go usaremos o CLI do Swaggo.
Com a lib instalada basta rodar na raiz do projeto o comando:
swag init -d adapter/http --parseDependency --parseInternal --parseDepth 2 -o adapter/http/docs
Isso vai gerar uma pasta chamada docs
na pasta adapter/http
.
Com isso vamos referenciar essa pasta na nossa rota no arquivo adapter/http/main.go
.
package main
import (
"context"
"fmt"
"log"
"net/http"
"github.com/boooscaaa/clean-go/adapter/postgres"
"github.com/boooscaaa/clean-go/di"
"github.com/gorilla/mux"
"github.com/spf13/viper"
/*adicionar essa linha */ httpSwagger "github.com/swaggo/http-swagger"
/*adicionar essa linha */ _ "github.com/boooscaaa/clean-go/adapter/http/docs"
)
func init() {
viper.SetConfigFile(`config.json`)
err := viper.ReadInConfig()
if err != nil {
panic(err)
}
}
// @title Clean GO API Docs
// @version 1.0.0
// @contact.name Vinícius Boscardin
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:port
// @BasePath /
func main() {
ctx := context.Background()
conn := postgres.GetConnection(ctx)
defer conn.Close()
postgres.RunMigrations()
productService := di.ConfigProductDI(conn)
router := mux.NewRouter()
/*adicionar essa linha */ router.PathPrefix("/swagger").Handler(httpSwagger.WrapHandler)
router.Handle("/product", http.HandlerFunc(productService.Create)).Methods("POST")
router.Handle("/product", http.HandlerFunc(productService.Fetch)).Queries(
"page", "{page}",
"itemsPerPage", "{itemsPerPage}",
"descending", "{descending}",
"sort", "{sort}",
"search", "{search}",
).Methods("GET")
port := viper.GetString("server.port")
log.Printf("LISTEN ON PORT: %v", port)
http.ListenAndServe(fmt.Sprintf(":%v", port), router)
}
Prontinho! Fácil não? Agora é só acessar no navegador o link http://localhost:3000/swagger/index.html
.
Sua vez
Vai na fé! Acredito totalmente em você, independente do seu nível de conhecimento técnico, você vai criar a melhor api em GO.
Se você se deparar com problemas que não consegue resolver, sinta-se à vontade para entrar em contato. Vamos resolver isso juntos.
Como que faz deploy disso ai?
Próximo post vamos configurar um ambiente para deploy com docker lá no heroku.