go-swagger

Go Swagger / OpenAPI with swaggo

github.com/swaggo/swag is the de-facto annotation-driven OpenAPI generator for Go. You annotate handlers with // @... comments, run the swag CLI, and get docs/swagger.json, docs/swagger.yaml, and docs/docs.go for the UI.

Core Rules

1. Docs are a contract. A field documented as required is the API's promise; a mismatch with the implementation is a bug.
2. Annotations live next to handlers. Not in a separate docs/ folder — comments rot when separated from code.
3. Regenerate on every change. swag init is part of the build (go generate or a Makefile target). Stale docs/ is worse than no docs.
4. The docs package must be imported. A blank import (_ "yourmod/docs") registers the spec at process start.
5. Use named structs for request/response bodies. swag cannot derive a schema from map[string]any or a primitive type.
6. Security definitions match implementation. If the API enforces JWT, declare @securityDefinitions.apikey Bearer and annotate every protected endpoint with @Security Bearer.

Install and Bootstrap

go install github.com/swaggo/swag/cmd/swag@latest
swag init                              # general info from main.go
swag init -g cmd/api/main.go           # custom main path
swag fmt                               # format annotation comments like gofmt

Wire the UI for your framework — choose one:

// Gin
import (
    swaggerFiles "github.com/swaggo/files"
    ginSwagger  "github.com/swaggo/gin-swagger"
)
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

// Echo
r.GET("/swagger/*", echoSwagger.WrapHandler)

// Fiber
app.Get("/swagger/*", fiberSwagger.WrapHandler(swaggerFiles.Handler))

// Chi / net/http
mux.Handle("/swagger/", httpSwagger.Handler(swaggerFiles.Handler))

Import the generated spec:

import _ "github.com/acme/myapi/docs"          // blank: just register
import docs "github.com/acme/myapi/docs"       // named: override host at runtime