Gin

Install

Install the swag CLI and the Gin integration:

go install github.com/swaggo/swag/cmd/swag@latest
go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files

Annotate your code

Add a general API annotation to main.go:

// main.go

// @title My API
// @version 1.0
// @BasePath /
package main

Add annotations to your handler functions:

// handlers/items.go

// GetItem godoc
// @Summary     Get a single item
// @ID          getItem
// @Tags        items
// @Param       id   path  int  true  "Item ID"
// @Success     200  {object}  Item
// @Router      /items/{id} [get]
func GetItem(c *gin.Context) {
    id := c.Param("id")
    c.JSON(200, gin.H{"id": id, "name": "Widget"})
}

Generate the spec

Run swag init from your project root to generate the docs/ directory:

swag init

Mount the spec endpoint

// main.go
import (
    _ "your-module/docs"
    ginSwagger "github.com/swaggo/gin-swagger"
    swaggerFiles "github.com/swaggo/files"
)

r := gin.Default()

// Swagger UI + raw spec
r.GET('/docs/*any', ginSwagger.WrapHandler(swaggerFiles.Handler))

r.Run(":8080")

The raw JSON spec is available at:

http://localhost:8080/docs/doc.json

Alternatively, serve it at /openapi.json:

r.GET('/openapi.json', func(c *gin.Context) {
    c.File('./docs/swagger.json')
})

Make it publicly accessible

Deploy your app or use a tunnel for local testing:

ngrok http 8080
# then use: https://<random>.ngrok.io/openapi.json

Verify

Visit /openapi.json in your browser. You should see a valid OpenAPI JSON document.

Paste this URL into Automiel’s import step.