How to add Swagger in Golang Gin.

Swagger is a popular tool for creating and maintaining API documentation. It allows developers to easily document their API endpoints, request and response formats, and other useful information for other developers who may be consuming the API. In this article, we will show you how to add Swagger to a Golang web application built with the Gin framework.

Unlike FastAPI, Gin does not have OpenAPI integration built in. With FastAPI when you add a route, documentation is already generated. With Gin, this is not the case. But recently I integrated Swagger UI in one of my Go backends and I wanted to document that process.

Step 1 : Setup Swagger CLI

The prime repository you should keep under your pillow is https://github.com/swaggo/swag. Both in terms of CLI and documentation.

We’ll install a CLI application called swag. Here’s how:

go get -u github.com/swaggo/swag/cmd/swag

# 1.16 or newer
go install github.com/swaggo/swag/cmd/swag@latest

The first command will download the dependencies to integrate in the server application. The second one is where we install the CLI. Now you should be able to run the swag command:

$ swag -h
NAME:
   swag - Automatically generate RESTful API documentation with Swagger 2.0 for Go.

USAGE:
   swag [global options] command [command options] [arguments...]

VERSION:
   v1.8.1

COMMANDS:
   init, i  Create docs.go
   fmt, f   format swag comments
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help (default: false)
   --version, -v  print the version (default: false)

Step 2: Install Gin-Swagger

Next, you will need to install the gin-swagger package. This package is a middleware that adds Swagger UI to your Gin application. You can install it using the following command:

go get -u github.com/swaggo/gin-swagger

Next, you will need to import the package in your main Go file:

import "github.com/swaggo/gin-swagger"
import "github.com/swaggo/gin-swagger/swaggerFiles"

Step 3 : Add a route for Swagger Docs

Now, you can add the middleware to your Gin application. In your main function, add the following code:

r := gin.Default()

url := ginSwagger.URL("http://localhost:8080/swagger/doc.json")
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

This code sets up a route for the Swagger UI and tells it to look for the Swagger documentation at the specified URL.

Step 4: Add General API Info to Gin API Server

Next, you will need to add annotations to your code to specify the information that will be displayed in the Swagger documentation. You can use the following annotations to specify the information for each endpoint:

// @Summary Add a new pet to the store
// @Description get string by ID
// @ID get-string-by-int
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string  "ok"
// @Router /string/{some_id} [get]

In this example, the @Summary annotation provides a brief summary of the endpoint, the @Description provides a more detailed description, the @ID provides a unique ID for the endpoint, the @Accept and @Produce annotations specify the request and response formats, the @Param annotation specifies the parameters for the endpoint, the @Success annotation specifies the expected response code and format, and the @Router annotation specifies the route for the endpoint.

Step 5: Generate swagger docs every time you modify doc string

Once you have added the annotations to your code, you can generate the Swagger documentation by running the following command:

swag init

This command will generate a doc.json file in the swagger folder in your project. The gin-swagger middleware that we added earlier will use this file to display the documentation in the Swagger UI.

Now you can run your application and visit the http://localhost:8080/swagger/ to see the swagger ui.

Conclusion

In conclusion, adding Swagger to a Golang web application built with the Gin framework is a straightforward process. By using the gin-swagger middleware and annotations, you can easily document your API endpoints and make them easily accessible to other developers.

You can find the complete source code for this tutorial on Github and Video.