[Golang] API Documentation Using Gin And Swaggo

In creating an API / Web Service, a developer needs to make clear documentation about the service being made. This will make it easier for clients who will consume our web service have no difficulty using it.

There are actually many ways to document a web service. one of them is using a SWAGGER.

As quoted from the official website swagger.io

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

In the Golang programming language, there are several libraries that can be used to create documentation using Swagger. one of the most widely used libraries is swaggo.

In this article, we will implement writing API documentation using gin and swaggo framework.

1.Import the swaggo library
The first thing to do is import the swaggo library in the project to be documented.

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

2.Generate Documentation
After successfully importing the library, the next step is to generate documentation. by running the code below in the project folder.

swag init
Initialize swagger

In the picture above, you can see that when we initialize Swagger, it will automatically create a docs folder.

3. Usage on code

After importing the library and generating documentation successfully, it’s time to apply the documentation to the code.

a. Import the required libraries

import (
"github.com/gin-gonic/gin"
"github.com/swaggo/files"
"github.com/swaggo/gin-swagger"

_ "./docs" // docs is generated by Swag CLI, you have to import it.
)

b. Write a general api annotation to display on the swagger

There are several texts that can be used for writing annotations, like:

Then re-initialize it using swag init And run it. And you will see the results as below

c. Add API Operation annotations In Controller Code

Add the Operation Annotation API to the controller code. This API Operation will later function to display the services that have been made.

Similar to writing general info annotations, API Operation annotations also have some text that can be used as a reference.

Then re-initialize it using swag init And run it. And you will see the results as below

Then the client only needs to use Swagger to view and try the web service that is made.

And finally we succeeded in making documentation for the web service that we created.

Happy Coding :)

reference:

  1. https://swagger.io/docs/specification/about/
  2. https://github.com/swaggo/swag

--

--

--

All about go language

Recommended from Medium

Decorator functions in Python

How to Protect Intellectual Property when Outsourcing?

Data Structures: A Summary

What’s Going On Behind the Screens: Ergo Weekly Dev Update October 6th

Installing minikube..

KUBERNETS with word press

A RecyclerView With Multiple View Type

A Docker Product Manager on What the Future Holds for Containers

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Amiruddin Saddam

Amiruddin Saddam

Backend Engineer at Jamtangan.com And will always learn something new.

More from Medium

SQL Injection with GO and Fix

gRPC In Go (with MongoDB) — Part 1

Concurrency [with sample project] in Golang

Introduction to gRPC