Introduction
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.
Prerequisites
- An already existing Gin server
You might consider Building a Book Store API in Golang With Gin if you are starting from scratch. I'll be using the same book store and extending over it to integrate Swagger UI.
How Swagger works with Gin
The way Swagger works with other Go backend is not different they all have the same mechanism. But how does it really work and what do we have to really do?
Swagger uses the Go comment system which is very well integrated with documentation already as we know. We write comments in a pre-defined way, details of which we will see further ahead in the post. But mostly it is divided into 2 parts. The server itself and the routes.
Swagger has a CLI binary which when runs converts these comment documents into OpenAPI compliant documentation. The resultant file also includes OpenAPI server specs in JSON and YAML format.
Lastly, we route the generated content via a handler in our backend.
How do we do that? Let's see.
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)
Documenting the Gin Server
When you look at Swagger UI documentation for any OpenAPI enabled website, you'd see something like this:
You might be familiar with the low half part of the UI. This is what Swagger docs are for i.e. to document the routes.
But before we deal with the lower 50% part I want you to notice in the above picture is the top 50% part. Right from the Swagger Petstore header to Find out more about the Swagger anchor link.
This part shows the metadata about the API server itself. In this section, we are going to build that part. You can find the code to start with here. We'll be continuing on that code.
First of all, we need to go get the packages we need to work with:
go get -u github.com/swaggo/files
go get -u github.com/swaggo/gin-swagger
Now after we have done that, let's look at our main.go file. This is the main.go at the moment:
package main
import "github.com/santosh/gingo/routes"
func main() {
router := routes.SetupRouter()
router.Run(":8080")
}
Add a route for Swagger Docs
We add a new router in the main function:
router.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
The modified file would look like this:
-import "github.com/santosh/gingo/routes"
+import (
+ "github.com/santosh/gingo/routes"
+ swaggerFiles "github.com/swaggo/files"
+ ginSwagger "github.com/swaggo/gin-swagger"
+)
func main() {
router := routes.SetupRouter()
+ router.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+
router.Run(":8080")
}
swaggerFiles.Handler here is the handler which has all the assets embedded in it. Assets like the HTML, CSS, and javascript files are shown on the documentation end.
ginSwagger.WrapHandler is a wrapper around http.Handler, but for Gin.
This should be enough for testing. Let's see how the docs render at <server address>/docs/index.html.
The good news is API documentation site is up. The bad news is it does not look like a normal API documentation site. What did we miss?
Generate swagger docs every time you modify doc string
Swagger documentation is stored in Go's own docstring. We have a special syntax that we follow. More on that later. But first, let us learn how to generate docs.
$ swag init
2022/05/25 23:59:16 Generate swagger docs....
2022/05/25 23:59:16 Generate general API Info, search dir:./
2022/05/25 23:59:16 create docs.go at docs/docs.go
2022/05/25 23:59:16 create swagger.json at docs/swagger.json
2022/05/25 23:59:16 create swagger.yaml at docs/swagger.yaml
We run swag init every time we update docs for our API. This generates 3 files inside a sub directory called docs/.
$ tree docs
docs
├── docs.go
├── swagger.json
└── swagger.yaml
0 directories, 3 files
swagger.json and swagger.yaml are the actual specification which you can upload to services like AWS API Gateway and similar services. docs.go is a glue code that we need to import into our server.
Let us now import the documentation to our main.go.
package main
import (
+ _ "github.com/santosh/gingo/docs"
"github.com/santosh/gingo/routes"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)
+// @title Gingo Bookstore API
func main() {
router := routes.SetupRouter()
As you can see we have imported docs the module by giving the full path of the module. We also have to prepend this import using _ because it is not explicitly used in main.go file.
You might also have noticed // @title Gingo Bookstore API line. Please note its position as this is important. It is just above the main() func. Also @title is not random here. It is one of the keywords which is documented under General API Info. We'll see more of these as we go, but for now, let's regenerate our docs and review the API docs.
Looks like we are getting somewhere. :D
Add General API Info to Gin API Server
We saw @title annotation in the last section. It is used to set the title for the API server. But it is not the only annotation available. There is a wide array of annotation in Swagger. You can find them in use in real life here.
I'm going to use some of them to construct metadata on my doc site.
// @title Gin Book Service
// @version 1.0
// @description A book management service API in Go using Gin framework.
// @termsOfService https://tos.santoshk.dev
// @contact.name Santosh Kumar
// @contact.url https://twitter.com/sntshk
// @contact.email sntshkmr60@gmail.com
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /api/v1
- Run
swag init. - Re-run the server.
- Check for update:
That's some metadata in there.
You might also have noticed that the API spec inside docs/ directory has changed. For example, here is the swagger.yaml file from the docs/ dir.
{
"swagger": "2.0",
"info": {
- "title": "Gingo Bookstore API",
- "contact": {}
+ "description": "A book management service API in Go using Gin framework.",
+ "title": "Gin Book Service",
+ "termsOfService": "https://tos.santoshk.dev",
+ "contact": {
+ "name": "Santosh Kumar",
+ "url": "https://twitter.com/sntshk",
+ "email": "sntshkmr60@gmail.com"
+ },
+ "license": {
+ "name": "Apache 2.0",
+ "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+ },
+ "version": "1.0"
},
+ "host": "localhost:8080",
+ "basePath": "/api/v1",
"paths": {}
}
Now it's time to add docs for API endpoints.
Add API Operation Info to API Endpoints
Just like General API Info for the main server, there also is API Operation for individual routes/endpoints handlers.
They are more diverse than what I'm going to use here. The ones I'm going to use are just a subset of them. If you want to check out some real examples, you can find them here on each of the route handlers.
Here is modified handlers/books.go:
"github.com/santosh/gingo/models"
)
-// GetBooks responds with the list of all books as JSON.
+// GetBooks godoc
+// @Summary Get books array
+// @Description Responds with the list of all books as JSON.
+// @Tags books
+// @Produce json
+// @Success 200 {array} models.Book
+// @Router /books [get]
func GetBooks(c *gin.Context) {
c.JSON(http.StatusOK, db.Books)
}
-// PostBook takes a book JSON and store in DB.
+// PostBook godoc
+// @Summary Store a new book
+// @Description Takes a book JSON and store in DB. Return saved JSON.
+// @Tags books
+// @Produce json
+// @Param book body models.Book true "Book JSON"
+// @Success 200 {object} models.Book
+// @Router /books [post]
func PostBook(c *gin.Context) {
var newBook models.Book
@@ -28,7 +41,14 @@ func PostBook(c *gin.Context) {
c.JSON(http.StatusCreated, newBook)
}
-// GetBookByISBN locates the book whose ISBN value matches the isbn
+// GetBookByISBN godoc
+// @Summary Get single book by isbn
+// @Description Returns the book whose ISBN value matches the isbn.
+// @Tags books
+// @Produce json
+// @Param isbn path string true "search book by isbn"
+// @Success 200 {object} models.Book
+// @Router /books/{isbn} [get]
func GetBookByISBN(c *gin.Context) {
isbn := c.Param("isbn")
- Run
swag init. - Re-run the server.
- Check for updates:
And here is the updated swagger.yaml:
basePath: /api/v1
+definitions:
+ models.Book:
+ properties:
+ author:
+ type: string
+ isbn:
+ type: string
+ title:
+ type: string
+ type: object
host: localhost:8080
info:
contact:
@@ -12,5 +22,58 @@ info:
termsOfService: https://tos.santoshk.dev
title: Gin Book Service
version: "1.0"
-paths: {}
+paths:
+ /books:
+ get:
+ description: Responds with the list of all books as JSON.
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: OK
+ schema:
+ items:
+ $ref: '#/definitions/models.Book'
+ type: array
+ summary: Get books array
+ tags:
+ - books
+ post:
+ description: Takes a book JSON and store in DB. Return saved JSON.
+ parameters:
+ - description: Book JSON
+ in: body
+ name: book
+ required: true
+ schema:
+ $ref: '#/definitions/models.Book'
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: OK
+ schema:
+ $ref: '#/definitions/models.Book'
+ summary: Store a new book
+ tags:
+ - books
+ /books/{isbn}:
+ get:
+ description: Returns the book whose ISBN value matches the isbn.
+ parameters:
+ - description: search book by isbn
+ in: path
+ name: isbn
+ required: true
+ type: string
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: OK
+ schema:
+ $ref: '#/definitions/models.Book'
+ summary: Get single book by isbn
+ tags:
+ - books
swagger: "2.0"
Notice the new definitions and paths section added. It is for models and the endpoints respectively.
Bonus: Router Group for /api/v1
It is always a good idea to prepend your routes with api/v1. v1 bit has a logic behind it. It is for the time when you have to introduce a breaking change which is not backward compatible. Maybe the input or the output has changes that might break millions of dependent client.
In these situations, you increment the version to something like api/v2 and let the older API server serve old from the old handler.
Right now all of the routes in gingo server start with /book. We are going to change that.
Here is the modified routes/routes.go.
func SetupRouter() *gin.Engine {
router := gin.Default()
- router.GET("/books", handlers.GetBooks)
- router.GET("/books/:isbn", handlers.GetBookByISBN)
- // router.DELETE("/books/:isbn", handlers.DeleteBookByISBN)
- // router.PUT("/books/:isbn", handlers.UpdateBookByISBN)
- router.POST("/books", handlers.PostBook)
+
+ v1 := router.Group("/api/v1")
+ {
+ v1.GET("/books", handlers.GetBooks)
+ v1.GET("/books/:isbn", handlers.GetBookByISBN)
+ // router.DELETE("/books/:isbn", handlers.DeleteBookByISBN)
+ // router.PUT("/books/:isbn", handlers.UpdateBookByISBN)
+ v1.POST("/books", handlers.PostBook)
+ }
return router
}
Here we use router.Group to create a group with a path of /api/v1. We then move all the route definitions into the group and surround it with braces. That is how we create a path route in Gin.
Conclusion
API documentation is an essential part of API documentation. Instead of documenting the endpoints anywhere else, we can document the routes right in the code. That way we only have 1 single source of truth. No need to maintain code and documentation separately. In turn, we get always up-to-date documentation.
Every backend server has some sort of support for Swagger UI. I have covered the basics for Gin, but if you use any other framework, I encourage you to look for your own framework.
Top comments (0)