In this article we discuss the use of swagger

We often need to use interface documentation in our work, so how to write interface documentation? What potholes are there? In the beginning, we wrote documents in Word, and later we wrote documents in Markdown. However, these methods are not conducive to maintenance, and later we find that the interface has been changed and the document is still the same, which is not conducive to maintenance. And every time we need to use Postman tool interface development test, and its tedious trouble. I found Swagger by accident and liked to write documents with Swagger from then on. It can automatically generate documentation, and can be used directly to do interface testing.

Install Swagger first

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

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

Copy the code

1. Import file introduces Swagger configuration


package main

import (
	"ginLearn.com/controller"
	_ "ginLearn.com/docs"
	"github.com/gin-gonic/gin"
	"github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
)

// @title GinSwagger // @version 1.0 // @description GinSwagger Example Project // @contact.name hanyun // @contact.url // @contact.email [email protected] // @license.name Apache 2.0 // @ license. The url http://www.apache.org/licenses/LICENSE-2.0.html / / @ host localhost: 8080 funcmain() {
	router := gin.Default()
	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	router.GET("/api/v1", controller.Index)
	router.Run()
}


Copy the code

Swagger can’t parse pages properly because I use gomodule. I define module ginLearn.com. You can replace “ginLearn.com” with your own definition.

Swagger Service annotation explanation

// @title GinSwagger displayed on title on the Web side // @version 1.0 Defines the version of the interface // @description GinSwagger sample project home page display. / / @ securityDefinitions apikey ApiKeyAuth API authentication / / @inHeader Method for sending authentication // @name Authorization method for the back end to obtain authentication // @contact.name hanyun contact email // @contact.url Home page address of a contact // @contact.email [email protected] Contact email // @license.name Protocol used in Apache 2.0 documents // @license.url The http://www.apache.org/licenses/LICENSE-2.0.html protocol address / / @ host localhost: 8080 document server addressCopy the code

2. Add comments to specific methods


package controller

import (
	"ginLearn.com/response"
	"github.com/gin-gonic/gin") / / @ / / @ Id Tags front page 1 / / @ / / @ the Summary for the home page data Description quantity price | | | | project / / @ Description | : -- -- -- -- -- -- -- - | -- -- -- -- -- -- -- -- : | : - : | / / @ Description | the | | | 5 6000 yuan / / @ Description | the | | | 12 3800 yuan / / @ Description | iMac | 234 | 10000 yuan  | // @Produce json // @Security ApiKeyAuth // @Param id path inttrue "User id"
// @Param token header string true "User token"
// @Param name query string false "Username"
// @Param img formData file false "File"
// @Success 200 object  response.Result "Success"
// @Failure 400 object  response.Result "Failure"
// @Router /api/v1/{id} [get]
func Index(c *gin.Context) {
	c.JSON(4000, response.Result{})
}



Copy the code

Swagger Interface Remarks Description

@summary is a description of the interface. @ID is a global identifier. All interface documents do not contain ids. The @security ApiKeyAuth interface means that this is an interface that requires authentication, Corresponding. / / @ securityDefinitions apikey ApiKeyAuth @ Version shows the Version of the interface @ the Accept said the request the request type @ Param said parameters respectively have the following parameters noun type data types Whether attributes must be commented (optional arguments), separated by Spaces. @success indicates that a request is returned after Success. It has the following parameters: request return status code, parameter type, data type, comment @failure A request is returned after Failure with the same parameters as @Router. This function defines the request route and contains the request mode of the route.Copy the code

Sometimes we need markdown tables to write documents, and Swagger’s comments support Markdown syntax

/ / @ Description quantity price | | | | project / / @ Description | : -- -- -- -- -- -- -- - | -- -- -- -- -- -- -- -- : | : - : | / / @ Description | the | | | 5 6000 yuan / / @ Description | the | | | 12 3800 yuan / / @ Description | iMac | 234 | 10000 yuan |Copy the code

Need source partners can go to Baidu cloud download

Link: pan.baidu.com/s/11_9zBngn… Extraction code: KFPH