Make swagger from your HTTP Rest full in Golang

One of the best tools for document Backend API is Swagger. And also can send data at the endpoint easily with no other tools. In this article, we will set up Swagger for restful API for Golang.

Golang has powerful as GRPC to swagger. But I didn’t use it in the current project. Anyway, converting GRPC to HTTP and making Swagger automatically with this project is possible.

Install Swagger Golang package

The Swaggo is one of the best libraries that can make Swagger for HTTP server requests. It supports many HTTP libraries in Golang, such as:

In this article I going to explain about the net/http, one can easily with below link.

text
https://github.com/swaggo/http-swagger

Install Swagger with Golang

bash
go install github.com/swaggo/swag/cmd/swag@latestswag init

Initial Swagger

go
//
@title title//
@version 2.0//
@description This is a sample server corepass server.//
@termsOfService http://swagger.io/terms///
@contact.name API Support//
@contact.url http://www.swagger.io/support//
@contact.email support@swagger.io//
@license.name Apache 2.0//
@license.url http://www.apache.org/licenses/LICENSE-2.0.html//
@query.collection.format multi//
@securityDefinitions.basic BasicAuth//
@externalDocs.description OpenAPI//
@externalDocs.url https://swagger.io/resources/open-api/
func InitialSwagger() {
    // programmatically set swagger info // docs.SwaggerInfo.Host = config.ServerHttpAddress()
    docs.SwaggerInfo.Schemes = []string{
        "https", "http"
    }
    r := mux.NewRouter()
    r.PathPrefix("/swagger/").Handler(httpSwagger.Handler(httpSwagger.URL("/swagger/doc.json"),
    //The url pointing to API definition httpSwagger.DeepLinking(true),
    httpSwagger.DocExpansion("none"), httpSwagger.DomID("swagger-ui"),)).Methods(http.MethodGet) go
    http.ListenAndServe(config.SwaggerUrl(), r) logger.Info("Swagger Server Server : ",
    config.SwaggerUrl())
}

Example of install swagger

Write swagger for show in the router

Every endpoint need detail of of endpoint.

go
// ShowAccount godoc// @Summary      Show an account// @Description  get string by ID// @Tags
accounts// @Accept       json// @Produce      json// @Param        id   path      int  true
"Account ID"// @Success      200  {object}  model.Account// @Failure      400  {object}
httputil.HTTPError// @Failure      404  {object}  httputil.HTTPError// @Failure      500  {object}
httputil.HTTPError// @Router       /accounts/{id} [get]

Attribute

go
// @Param   enumstring  query     string     false  "string enums"       Enums(A, B, C)// @Param
enumint     query     int        false  "int enums"          Enums(1, 2, 3)// @Param   enumnumber
query     number     false  "int enums"          Enums(1.1, 1.2, 1.3)// @Param   string      query
string     false  "string valid"       minlength(5)  maxlength(10)// @Param   int         query
int        false  "int valid"          minimum(1)    maximum(10)// @Param   default     query
string     false  "string default"     default(A)// @Param   example     query     string     false
"string example"     example(string)// @Param   collection  query     []string   false
"string collection"  collectionFormat(multi)// @Param   extensions  query     []string   false
"string collection"  extensions(x-example=test,x-nullable)

Good Examples that wrote in their repository

text
https://github.com/swaggo/swag/blob/master/example/basic/api/api.go

Param Type

  • query
  • path
  • header
  • body
  • formData

Command for run Swagger

text
swag init -g path/router.gofor example :swag init -g app/router/router.go