swag

swag

Automatically generate RESTful API documentation with Swagger 2.0 for Go.

What is swag?

swag converts Go annotations to Swagger Documentation 2.0. And provides a variety of builtin web framework lib. Let you can quickly integrated in existing golang project(using Swagger UI) .

Contents

• Generate Swagger 2.0 docs
• How to use it with gin?
• Declarative Comments Format
  • General API info
  • API Operation
• Supported Web Framework

Generate Swagger 2.0 docs

1. Add comments to your API source code, See Declarative Comments Format

2. Download swag by using:

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

1. Run the swag in project root folder which contains main.go file, The swag will parse your comments and generate required files(docs folder and docs/doc.go).

$ swag init

How to use it with gin?

1. After using swag to generate Swagger 2.0 docs. Import following packages:

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

1. Added API Operation annotations in main.go code:

package main

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

	_ "github.com/swaggo/gin-swagger/example/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()

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

	r.Run()
}

1. Added General API Info annotations in handler/controller code

// @Summary Add a new pet to the store
// @Description get string by ID
// @ID get-string-by-int
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string	"ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]
func GetStringByInt(c *gin.Context) {
	//write your code
}

// @Description get struct array by ID
// @ID get-struct-array-by-string
// @Accept  json
// @Produce  json
// @Param   some_id     path    string     true        "Some ID"
// @Param   offset     query    int     true        "Offset"
// @Param   limit      query    int     true        "Offset"
// @Success 200 {string} string	"ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-struct-array-by-string/{some_id} [get]
func GetStructArrayByString(c *gin.Context) {
	//write your code
}

type Pet3 struct {
	ID int `json:"id"`
}

1. Run it, and browser to http://localhost:8080/swagger/index.html. You will see Swagger 2.0 Api documents as bellow:

Declarative Comments Format

General API Info

API Operation

Mime Types

  json
  application/json
  xml
  text/xml
  plain
  text/plain
  html
  text/html
  mpfd
  multipart/form-data
  json-api
  application/vnd.api json

Supported Web Framework

• gin-swagger

TODO

• supplement better documentation
• add more example
• support other web Framework

About the Project

This project was inspired by swagger but simplified the usage of complexity and support a variety of web framework.