Gin's code example using swagger to generate interface documents

What is swagger

Swagger is a standardized and complete framework for generating, describing, calling, and visualizing RESTful Web services. It uses YAML or JSON format to define the structure of the API, including request, response, parameters and other information. The main features of Swagger include:

• Normative:Swagger defines a set of API description standards, allowing developers to describe APIs in a unified way.
• Automatically generate documents:Swagger can automatically generate API documents, allowing developers and users to quickly understand how to use APIs.
• Interactive Documentation:Swagger provides an interactive user interface where users can try API calls directly in the document.
• Code generation:Swagger can automatically generate server and client code according to the API description, saving development time.
• Community Support:Swagger has extensive community support, and many developers and companies are using it to build and manage their APIs.
• Toolchain integration:Swagger can be integrated with many development tools and platforms, such as Spring Boot, .NET Core, etc.
• Version control: Swagger supports API version control, making API iteration more flexible.

Swagger is now commonly used in conjunction with OpenAPI Specification (OAS), an open standard powered by the Linux Foundation to describe APIs. Swagger's tools and ecosystem now also support OAS.

swagger installation

$ go get -u /swaggo/swag/cmd/swag 
#1.16 and above$ go install /swaggo/swag/cmd/swag@latest

gin-swagger

Install

go get -u /swaggo/gin-swagger

use

Want to usegin-swaggerTo automatically generate interface documents for your code, the following three steps are generally required:

• Add declarative comments to the interface code according to swagger requirements, and refer to the declarative comment format for details.
• Use swag tool to scan code to automatically generate API interface document data
• Rendering online interface document pages using gin-swagger

Add Comment

Write down project-related information in the form of comments on the main function of the program entrance.

package main

// @title Write the title here// @version 1.0
// @description Write description information here// @termsOfService /terms/

// @ @ Write the contact information here// @ /support
// @ support@

// @ Apache 2.0
// @ /licenses/LICENSE-2.

// @host Write the host of the interface service here// @BasePath Write base path herefunc main() {
	r := ()

	//  ...

	()
}

The interface function that handles requests in your code (usually located at the controller layer) is commented as follows:

// GetCommunityHandler Get the community list// @Summary Get the community list// @Description Get the community list// @Tags Community List// @Accept json
// @Produce json
// @Param Authorization header string true "Bearer user token"// @Success 200 {object} "Success"// @Router /community [get]
// @Request Body "Community List"func GetCommunityHandler(c *) {
    // Get the community list (Community_id, Community_name)    list, err := ()
    if err != nil {
       (c, 200, "Failed to get the community list")
       return
    }
    (c, list)
}

Generate interface document data

Run the command in the project root directory:swag init, the annotation will be parsed and the required file will be generated (docFolders and,,）

swag init

After executing the command, the following file will be generated

./docs
├── 
├── 
└── 

Then register the route in the project code and introduce it as followsgin-swaggerRelated content:

import (

	_ "project/docs"  // Don't forget to import the docs generated in the previous step
	gs "/swaggo/gin-swagger"
	"/swaggo/gin-swagger/swaggerFiles"

	"/gin-gonic/gin"
)

Register swagger API-related routes

("/swagger/*any", ())

The project program is running, open the browser and visit http://localhost:8080/swagger/ to see the Swagger Api document.

gin-swaggerAlso providedDisablingWrapHandlerFunctions, which facilitate us to disable Swagger by setting certain environment variables. For example:

("/swagger/*any", (, "NAME_OF_ENV_VARIABLE"))

Probable problems

When I use it, I found that it was executingswag initWhen , it will not be found.

Solution:

Plus on the command line --parseDependency --parseInternal

swag init --parseDependency --parseInternal

This is the end of this article about code examples of Gin using swagger to generate interface documents. For more related content of Gin swagger interface documents, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!