swagger

README

Swagger 2.0

---

This project contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0). It provide tools to work with swagger specifications.

Swagger is a simple yet powerful representation of your RESTful API.

Announcements

You may join the discord community by clicking the invite link on the discord badge. .

• 2026-08-15 : Docker image users - shipping v0.36.4 to address critical vulnerability in golang

• 2026-08-11 : v0.36.3 lands soon (ETA 08/14)

  • codegen fixes
  • spec gen updates deferred to v0.36.4 (~ 08/21: faster scanner, enhanced TUI tool)
    • see preview of the playground tool (online spec gen): https://go-openapi.github.io/codescan/playground
  • doc site revamp deferred to v0.36.5 (~ end of August)

• 2026-07-31 : v0.36.0 is released

  • codegen: new option to serve multipart files as a stream
  • spec gen:
    • new TUI tool (see https://github.com/go-openapi/codescan#work-with-the-tui)
    • auto discovery of polymorphic subtypes
    • swagger:omit to use with embedded structs
  • a significant update of our documentation site is ongoing, but couldn't make it to this release.

Documentation

https://goswagger.io

Features

go-swagger brings to the go community a complete suite of fully-featured, high-performance, API components to work with a Swagger API: server, client and data model.

• Generates a server from a swagger specification
• Generates a client from a swagger specification
• Generates a CLI (command line tool) from a swagger specification (alpha stage)
• Supports most features offered by jsonschema and swagger, including polymorphism
• Generates a swagger specification from annotated go code
• Additional tools to work with a swagger spec
• Great customization features, with vendor extensions and customizable templates

Our focus with code generation is to produce idiomatic, fast go code, which plays nice with golint, go vet etc.

More details.

Project status

This project supports OpenAPI 2.0. At this moment it does not support OpenAPI 3.x.

go-swagger is now feature complete and has stabilized its API.

Most features and building blocks are now in a stable state, with a rich set of CI tests.

The go-openapi community actively continues bringing fixes and enhancements to this code base.

There is still much room for improvement: contributors and PR's are welcome. You may also get in touch with maintainers on our .

Installing

go install github.com/go-swagger/go-swagger/cmd/swagger@latest

go-swagger is also available as binary or docker releases as well as from source: more details.

Try it

Try go-swagger in a free online workspace using Gitpod:

Security

go-swagger turns an OpenAPI 2.0 specification into source code. Treat a specification like any other untrusted input: if you obtained it from a remote or untrusted location, review its contents before generating code from it.

The generator never executes the spec, and the generated code runs only when you build and import it. We have hardened the generators against an adversarial spec that tries to inject unwanted Go into the artifacts it produces — identifiers, struct tags, doc comments and CLI string literals are sanitized or escaped — which substantially reduces the exposure. It is not, however, a substitute for reviewing what you generate. In particular:

• Remote $refs. A spec may reference other documents, possibly over the network. Those references are resolved and folded into the generated code, so inspect any external reference you do not control.
• The x-go-type extension. By design, this extension lets the spec choose the Go type for a field — including an arbitrary imported package. That capability cannot easily be safeguarded: a spec using x-go-type can make your generated code import and depend on a package of its choosing. Always review specs that rely on it.

When in doubt, generate into a scratch directory, read the diff, and only then wire it into your build.

Licensing

The toolkit itself is licensed under an Apache Software License 2.0: SPDX-License-Identifier: Apache-2.0.

Just like swagger, this does not cover code generated by the toolkit. That code is entirely yours to license however you see fit.

Licence scan on dependencies

Documentation

Overview

Package swagger (2.0) provides a powerful interface to your API.

Contains an implementation of Swagger 2.0. It knows how to serialize, deserialize and validate swagger specifications.

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment.

With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. We created Swagger to help fulfill the promise of APIs.

Swagger helps companies like Apigee, Getty Images, Intuit, LivingSocial, McKesson, Microsoft, Morningstar, and PayPal build the best possible services with RESTful APIs.Now in version 2.0, Swagger is more enabling than ever. And it's 100% open source software.

More detailed documentation is available at https://goswagger.io.

Install:

go install github.com/go-swagger/go-swagger/cmd/swagger@latest

The implementation also provides a number of command line tools to help working with swagger.

Treat a specification like any other untrusted input: if you obtained it from a remote or untrusted location, review its contents before generating code from it.

To validate a spec:

swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/old-v3.2.0-dev/examples/v2.0/json/petstore-expanded.json

To generate a server for a swagger spec document:

swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]]

To generate a client for a swagger spec document:

swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]]

To generate a swagger spec document for a go application:

swagger generate spec -o ./swagger.json

There are several other sub commands available for the generate command

Sub command | Description
------------|----------------------------------------------------------------------------------
operation   | generates one or more operations specified in the swagger definition
model       | generates model files for one or more models specified in the swagger definition
support     | generates the api builder and the main method
server      | generates an entire server application
client      | generates a client for a swagger specification
spec        | generates a swagger spec document based on go code

Generating code

You're free to add files to the directories the generated code lands in, but the files generated by the generator itself will be regenerated on following generation runs so any changes to those files will be lost. However extra files you create won't be lost so they are safe to use for customizing the application to your needs.

To generate a server for a swagger spec document:

swagger generate server -f ./swagger.json -A [application-name] [--principal [principal-name]]