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

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.

Repositório