go-swagger3 vs swaggo/swag vs go-swagger¶
Three Go tools generate API specs from source code comments. The biggest difference is the spec version they produce.
| go-swagger3 | swaggo/swag | go-swagger | |
|---|---|---|---|
| Output | OpenAPI 3.0 | Swagger 2.0 (v1); OpenAPI 3.1 in v2 release candidates | Swagger 2.0 only |
| Approach | Comments → spec | Comments → spec | swagger: comments → spec; also generates server/client code from a spec |
| Annotation style | @Param, @Success, @Router… |
@Param, @Success, @Router… |
swagger:route, swagger:model, swagger:parameters… |
| Generics | Yes (Page[Pet]) |
Yes | Limited |
| Swagger UI | Built in for net/http, Gin, Echo, chi, mux, Fiber, Hertz, Buffalo, Flamingo, Atreugo | Separate packages (gin-swagger, echo-swagger, …) |
swagger serve command |
| Annotation formatter | go-swagger3 fmt |
swag fmt |
No |
| Output formats | JSON, YAML | JSON, YAML, Go (docs.go) |
JSON, YAML |
Checked against swag v1.16.6 / v2.0.0-rc6 and go-swagger v0.36.7 (November 2026).
When to choose which¶
Choose go-swagger3 if you want OpenAPI 3 today from annotations that look like swag's. Most swag comments work
unchanged, so moving an existing project is mostly a matter of running a different generator. OpenAPI 3 brings
oneOf/anyOf, nullable, multiple servers, request bodies with several content types, and better support in
modern tooling (client generators, API gateways, Postman, Redocly).
Choose swaggo/swag if Swagger 2.0 is enough for your consumers, or you need its generated docs.go package. Its
v2 line targets OpenAPI 3.1 but is still a release candidate.
Choose go-swagger if you want to generate Go servers and clients from a hand-written Swagger 2.0 spec (design-first), rather than generate a spec from code.
Moving from swag¶
- Install go-swagger3:
go install github.com/parvez3019/go-swagger3@latest. - Run it on your module:
go-swagger3 --module-path . --output oas.json --schema-without-pkg. - Replace
@host/@BasePathwith@Server, and@securityDefinitions.*with@SecurityScheme. - Swap
gin-swagger/echo-swaggerfor the go-swagger3 adapter for your framework, e.g. Gin or Echo.
The migration guide maps every swag annotation to its go-swagger3 equivalent.