The introduction

  • Interface documentation is a very important part of the project
  • How to maintain interface documentation is a problem that most developers have encountered (and a headache)
  • By writing annotations or by scanning code to generate annotations, you can generate a uniform standard interface document and a set of Swagger tools
  • Today I will take you to learn how to use Swagger to generate interface documents in gin project
  • Github code address

1. Install SWAG

go get github.com/swaggo/swag/cmd/swag
Copy the code

Move GOPATH/bin/swag to the global $GOBIN directory to verify that the installation is successful

swag -v
Copy the code

2. Install gIN-Swagger

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

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

3. API annotation writing and generation

Gin – Swagger’s annotation specification

/ / @ the Summary in this paper
/ / @ the Description
// @description Detailed Description of the interface
// @id Global identifier
// @version Indicates the interface Version
// @tags interface grouping
// @accept JSON browser can handle data types
// @produce json sets the type and encoding of the returned data
// @param Parameter format from left to right: parameter name, input type, data type, Mandatory, and comment Example: id query int true "id"
From left to right: status code, parameter type, data type, and comment Case: 200 {string} string "OK"
From left to right: status code, parameter type, data type and comment Case: 400 {object} web.APIError "We need ID!!"
// @router: /testapi/get-string-by-int/{some_id} [get]
// @contact.name Interface contact
// @contact.url Url of the contact
// @contact.email Email address of the contact
Copy the code

There are several types of param

  • Like a/user to query? username=Jack&age=18
  • The body needs to put the data in the body for the request
  • FormData multipart/request form – data *
  • The path/user / 1
  • The header in the header

Tool added API returns

type JSONRET struct {
	Error_code int         `json:"error_code"`
	Msg        string      `json:"msg"`
	Data       interface{} `json:"data"`
}

func JSONP(c *gin.Context, code int, msg string, data interface{}) {
	h := JSONRET{
		code, GetMsg(code, msg), data,
	}
	c.JSONP(200, h)
}
Copy the code

App/Models /user.go added a return structure (to make it easier for interface documents to return specific fields)

type UserSwagger struct {
	Lists []*User
	Total int
}
Copy the code

Controller adds document annotations

// @summary user list
// @Produce json
// @failure 400 {object} tool.jsonret "Parameter error"
// @failure 20001 {object} tool.JSONRET "Token authentication failed"
// @failure 20002 {object} tool.JSONRET "Token has timed out"
// @failure 20004 {object} tool.jsonret "Token error"
// @failure 20005 {object} tool.JSONRET "Token parameter cannot be empty"
// @success 0 {object} models.UserSwagger
// @Router /api/v1/users [get]
Copy the code

Add project annotations in main.go

// @title go-API framework
/ / @ version 1.0
// @description gin- Web framework
// @termsofservice https://github.com/18211167516/Go-Gin-Api
// @contact.name baichonghua
// @contact.email [email protected]
/ / @ host 127.0.0.1:8080
Copy the code

Finally, execute the command to generate the document, which generates the docs directory

swag init
Copy the code

4. Add an access interface document route

Note that the current project docs should be imported, otherwise an error Failed to load spec will be reported.

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
Copy the code

5. Review documentation verification

http://127.0.0.1:8080/swagger/index.html
Copy the code

Here we have successfully generated the project API document using Swagger

  • The related documents
  • gin-swagger
  • swager-go

6. Series of articles

  • Serialized a Golang environment build
  • Serial II installation Gin
  • Serial three defines the directory structure
  • Serial four builds case API1
  • Serial five builds case API2
  • Serial six access Swagger interface document
  • Serial seven Log components
  • Serial eight gracefully restarts and stops
  • Serial Makefile build
  • Serial Cron timing mission
  • Serial build command line tools
  • Create a dedicated Cache(First Day)
  • Create your own Cache in 3 days (Second Day)
  • Create a dedicated Cache(Third Day)