DEV Community 👩‍💻👨‍💻

Cover image for Documentanto uma api Go com Swagger
Vinícius Boscardin
Vinícius Boscardin

Posted on

Documentanto uma api Go com Swagger

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) {
    ...
}
Enter fullscreen mode Exit fullscreen mode

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) {
    ...
}
Enter fullscreen mode Exit fullscreen mode

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() {
    ...
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
}

Enter fullscreen mode Exit fullscreen mode

Prontinho! Fácil não? Agora é só acessar no navegador o link http://localhost:3000/swagger/index.html.

Image description

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.

Repositório

Top comments (0)

🌚 Browsing with dark mode makes you a better developer.

It's a scientific fact.