Swagger 2.0 implementation for go

go get


Swagger 2.0 Circle CI Slack Status

license GoDoc

This API is not stable yet, when it is stable it will be distributed over

There is a code coverage report available in the artifacts section of a build. Unfortunately using coveralls made the build unstable.

Contains an implementation of Swagger 2.0. It knows how to serialize and deserialize 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.



go get -u

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

Currently there is a spec validator tool:

    swagger validate

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

Much improved documentation is in the works and will actually explain how to use this tool in much more depth. To learn about which annotations are available and how to use them for generating a spec from any go application (generating a spec is not opinionated), you can take a look at the files used for testing the parser.

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


For now what exists of documentation on how all the pieces fit together, is described in this doc

What's inside?

For a V1 I want to have this feature set completed:

  • Documentation site
  • Play nice with golint, go vet etc.
  • An object model that serializes to swagger yaml or json
  • A tool to work with swagger:
    • validate a swagger spec document:
    • validate against jsonschema
    • validate extra rules outlined here
      • definition can't declare a property that's already defined by one of its ancestors (Error)
      • definition's ancestor can't be a descendant of the same model (Error)
      • each api path should be non-verbatim (account for path param names) unique per method (Error)
      • each security reference should contain only unique scopes (Warning)
      • each security scope in a security definition should be unique (Warning)
      • each path parameter should correspond to a parameter placeholder and vice versa (Error)
      • each referencable definition must have references (Warning)
      • each definition property listed in the required array must be defined in the properties of the model (Error)
      • each parameter should have a unique name and type combination (Error)
      • each operation should have only 1 parameter of type body (Error)
      • each reference must point to a valid object (Error)
      • every default value that is specified must validate against the schema for that property (Error)
      • every example that is specified must validate against the schema for that property (Error)
      • items property is required for all schemas/definitions of type array (Error)
    • serve swagger UI for any swagger spec file
    • code generation
      • generate api based on swagger spec
      • generate go client from a swagger spec
    • spec generation
      • generate spec document based on the code
        • generate meta data (top level swagger properties) from package docs
        • generate definition entries for models
          • support composed structs out of several embeds
          • support allOf for composed structs
        • generate path entries for routes
        • generate responses from structs
          • support composed structs out of several embeds
        • generate parameters from structs
          • support composed structs out of several embeds
  • Middlewares:
    • serve spec
    • routing
    • validation
    • additional validation through an interface
    • authorization
      • basic auth
      • api key auth
    • swagger docs UI
  • Typed JSON Schema implementation
    • JSON Pointer that knows about structs
    • JSON Reference that knows about structs
    • Passes current json schema test suite
  • extended string formats
    • uuid, uuid3, uuid4, uuid5
    • email
    • uri (absolute)
    • hostname
    • ipv4
    • ipv6
    • credit card
    • isbn, isbn10, isbn13
    • social security number
    • hexcolor
    • rgbcolor
    • date
    • date-time
    • duration
    • password
    • custom string formats


After the v1 implementation extra transports are on the roadmap.

Many of these fall under the maybe, perhaps, could be nice to have, might not happen bucket:

  • Formats:
    • custom serializer for XML to support namespaces and prefixes
  • Tools:
    • Code generation:
      • generate "sensible" random data based on swagger spec
      • generate tests based on swagger spec for client
      • generate tests based on swagger spec for server
      • generate markdown representation of swagger spec
      • watch swagger spec file and regenerate when modified
    • Spec generation:
      • watch application folders and regenerate the swagger document
  • Middlewares:
    • swagger editor
    • swagger UI
    • authorization:
      • oauth2
        • implicit
        • access code
        • password
        • application
  • Transports:
    • swagger socket (swagger over tcp sockets)
    • swagger websocket (swagger over websockets)
    • swagger proxy (assemble several backend apis into a single swagger spec and route the requests)
    • swagger discovery (repository for swagger specifications)