Golang to add a swagger [gin-swagger]

Copyright: Attribution, allow others to create paper-based, and must distribute paper (based on the original license agreement with the same license Creative Commons )

table of Contents

Installation gin plug

Installation swag Tools

Installation gin-swagger

Import gin-swagger

Interface documentation generated docs

Startup project

Description Interface Description

---

Go requires complete autonomy of operation before the development environment to build

Prepare in advance

Installation gin plug

go get -u -v github.com/gin-gonic/gin

 

Installation swag Tools

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

 

After execution, swag path where the PATH needs to be set, is provided as follows (if already set skip this step)

The $ GOPATH / bin added to your $ PATH:

export PATH = $PATH:$GOPATH/bin

 

Verify Success:

swag -v

The following message appears, it means that you have configured successfully

swag version v1.5.1

 

Installation gin-swagger

Two first need to download the installation package:

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

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

Above, preparations were already ready, start line and the code:

Description:

swagger implementation is modified by comments by way of the code and automatically generates interface document by means swag

Import gin-swagger

import "github.com/swaggo/gin-swagger" // gin-swagger middleware 

import "github.com/swaggo/gin-swagger/swaggerFiles" // swagger embed files

Gin-swagger sample code is as follows:

Code Example:

package main

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

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

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email [email protected]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host petstore.swagger.io
// @BasePath /v2
func main() {
	r := gin.New()
    
	config := &ginSwagger.Config{
		URL: "http://localhost:8080/swagger/doc.json", //The url pointing to API definition
	}
	// use ginSwagger middleware to 
	r.GET("/swagger/*any", ginSwagger.CustomWrapHandler(config, swaggerFiles.Handler))

	r.Run()
}

Interface documentation generated docs

Execution swag init interface documentation is automatically generated in the directory of main.go

swag init
2019/07/03 11:30:24 Generate swagger docs....
2019/07/03 11:30:24 Generate general API Info, search dir:./
2019/07/03 11:30:26 create docs.go at  docs/docs.go
2019/07/03 11:30:26 create swagger.json at  docs/swagger.json
2019/07/03 11:30:26 create swagger.yaml at  docs/swagger.yaml

 After execution, in the directory where main.go will generate a docs folder, as follows:

main.go

docs ----------

   |---docs.go

   |---swagger.json

   |----swagger.yaml

Startup project

go run main.go

Access:  HTTP: // localhost: 8080 / swagger / index.html you can see the swagger Interface

Interface is as follows:

Description Interface Description

Accessibility https://github.com/EDDYCJY/go-gin-example for the latest instructions

// @registered user

// @Description Register User

// @Accept multipart/form-data

// @Produce json

// @Param username formData string true "username"

// @Param password formData string true "password"

// @Success 200 {string} string "ok"

// @Router /register [post]

 

@param Special Instructions

For the post, the type of information submitted using the form inside the body formData

Url added to get or use the query type parameter

path need to use the type of path

@Param [Paramname] [path/query/formdata] [int/string] [true/false] [description]