Migrating from swaggo/swag to go-swagger3¶
go-swagger3 generates OpenAPI 3.0 natively. swag (v1) generates Swagger 2.0; swag v2 targets OpenAPI 3.1 (RC). This guide maps common swag annotations and UI mounts to go-swagger3.
Quick differences¶
| Topic | swag | go-swagger3 |
|---|---|---|
| Spec version | Swagger 2.0 (swagger: "2.0") |
OpenAPI 3.0.0 (openapi: "3.0.0") |
| Host / base path | @host, @BasePath |
@Server {url} {description} (repeatable) |
| Content types | @Accept / @Produce |
Same (@Accept, @Produce) |
| Security apply | Per-operation @Security |
Global @Security and per-operation @Security |
| Security define | @securityDefinitions.* |
@SecurityScheme / @SecurityScope |
| UI middleware | Separate repos (gin-swagger, …) |
In-repo adapters under swagger/<framework>/ |
| Format comments | swag fmt |
go-swagger3 fmt -d ./ |
| Generics | Foo[Bar] |
Foo[Bar] (schema id Foo_Bar) |
| Composition | JSONResult{data=Order} |
Same {field=Type} sugar |
Annotation mapping¶
General API info¶
| swag | go-swagger3 |
|---|---|
@title |
@Title |
@version |
@Version |
@description |
@Description |
@termsOfService |
@TermsOfServiceUrl |
@contact.name / .email / .url |
@ContactName / @ContactEmail / @ContactURL |
@license.name / .url |
@LicenseName / @LicenseURL |
@host + @BasePath |
@Server https://example.com/api/v1 Production |
@tag.name / @tag.description |
@tag.name / @tag.description |
@externalDocs.description / .url |
Same |
Operations¶
| swag | go-swagger3 |
|---|---|
@Summary |
@Title (summary) |
@Description |
@Description |
@Tags |
@Resource or @Tag |
@Accept / @Produce |
Same |
@Param |
Same shape; also supports Enums(), default(), minimum(), Format(), style(), explode() |
@Success / @Failure / @Response |
@Success / @Failure |
@Header (response) |
@ResponseHeader |
@Router /path [get] |
@Route or @Router |
@id |
@OperationId |
@deprecated |
@deprecated |
@Security ApiKeyAuth |
@Security ApiKeyAuth (on handler or globally) |
Struct tags¶
| swag | go-swagger3 |
|---|---|
example, enums, validation tags |
Same family (example, enum, minimum, …) |
swaggertype |
swaggertype or go-swagger3:"type=…" |
swaggerignore:"true" |
skip:"true" or go-swagger3:"-" / json:"-" |
| Field comments as descriptions | Supported (and description tag) |
Generate¶
# swag
swag init -g cmd/api/main.go
# go-swagger3
go-swagger3 --module-path . --main-file-path ./cmd/api/main.go --output oas.json --schema-without-pkg
Useful flags: --exclude, --quiet, --handler-path, --strict, --generate-yaml, --debug.
Format annotations:
go-swagger3 fmt -d ./
Serve Swagger UI¶
net/http¶
import "github.com/parvez3019/go-swagger3/swagger"
http.Handle("/swagger/", swagger.Handler(spec, swagger.Title("My API")))
gin¶
import ginswagger "github.com/parvez3019/go-swagger3/swagger/gin"
r.Any("/swagger/*any", ginswagger.WrapHandler(spec))
go get github.com/parvez3019/go-swagger3/swagger/gin
echo¶
import echoswagger "github.com/parvez3019/go-swagger3/swagger/echo"
e.Any("/swagger/*", echoswagger.WrapHandler(spec))
chi¶
import chiswagger "github.com/parvez3019/go-swagger3/swagger/chi"
r.Handle("/swagger/*", chiswagger.WrapHandler(spec))
gorilla/mux¶
import muxswagger "github.com/parvez3019/go-swagger3/swagger/mux"
r.PathPrefix("/swagger/").Handler(muxswagger.WrapHandler(spec))
fiber¶
import fiberswagger "github.com/parvez3019/go-swagger3/swagger/fiber"
app.All("/swagger/*", fiberswagger.WrapHandler(spec))
hertz / buffalo / flamingo / atreugo¶
Same pattern — import github.com/parvez3019/go-swagger3/swagger/<framework> and call WrapHandler(spec). See examples/ and each adapter’s package comment.
Each adapter is a separate Go module so you only pull the frameworks you use.
Security schemes¶
// swag
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
// go-swagger3
// @SecurityScheme ApiKeyAuth apiKey header Authorization
// @Security ApiKeyAuth
HTTP bearer / OAuth2 / OpenID Connect use @SecurityScheme forms documented in the README.
What stays annotation-driven¶
Like swag, go-swagger3 does not introspect gin/echo/fiber route tables. Handlers still need @Router (or @Route) comments.
OpenAPI 3.1¶
go-swagger3 targets OpenAPI 3.0.0 today. A 3.1 output mode is planned once 3.0 coverage is complete; prefer 3.0 tooling (Swagger UI, spectral, openapi-generator) for now.