Automatically generate RESTful API documentation with Swagger 2.0 for Go.
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) .
- Generate Swagger 2.0 docs
- How to use it with gin?
- Declarative Comments Format
- Supported Web Framework
-
Add comments to your API source code, See Declarative Comments Format
-
Download swag by using:
$ go get -u github.com/swaggo/swag/cmd/swag- Run the swag in project root folder which contains
main.gofile, The swag will parse your comments and generate required files(docsfolder anddocs/doc.go).
$ swag init- 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- Added API Operation annotations in
main.gocode:
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 support@swagger.io
// @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()
}- Added General API Info annotations in
handler/controllercode
// @Summary Add a new pet to the store
// @Description get string by ID
// @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
// @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"`
}y 4. Run it, and browser to http://localhost:8080/swagger/index.html. You will see Swagger 2.0 Api documents as bellow:
| annotation | description |
|---|---|
| title | Required. The title of the application. |
| version | Required. Provides the version of the application API. |
| description | A short description of the application. |
| termsOfService | The Terms of Service for the API. |
| contact.name | The contact information for the exposed API. |
| contact.url | The URL pointing to the contact information. MUST be in the format of a URL. |
| contact.email | The email address of the contact person/organization. MUST be in the format of an email address. |
| license.name | Required. The license name used for the API. |
| license.url | A URL to the license used for the API. MUST be in the format of a URL. |
| host | The host (name or ip) serving the API. |
| BasePath | The base path on which the API is served. |
| annotation | description |
|---|---|
| description | A verbose explanation of the operation behavior. |
| summary | A short summary of what the operation does. |
| accept | A list of MIME types the APIs can consume. Now only json application type. |
| produce | A list of MIME types the APIs can produce. Now only json application type. |
| param | Parameters that separated by spaces. param name,param type,data type,is mandatory?,comment |
| success | Success response that separated by spaces. return code,{param type},data type,comment |
| failure | Failure response that separated by spaces. return code,{param type},data type,comment |
| router | Failure response that separated by spaces. path,[httpMethod] |
- support other Mime Types, eg: xml
- supplement better documentation
- add more example
- support other web Framework
This project was inspired by swagger but simplified the usage of complexity and support a variety of web framework.
