README
¶
Swagger 2.0 
This package contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.
Swagger is a simple yet powerful representation of your RESTful API.
Swagger in a nutshell
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.
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
- 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.
Project status
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 slack channel.
Documentation
FAQ
Q&A contributed by the community:
How is this different from go generator in swagger-codegen?
tl;dr The main difference at this moment is that this one actually works...
The swagger-codegen project only generates a workable go client and even there it will only support flat models. Further, the go server generated by swagger-codegen is mostly a stub.
Motivation Why is this not done as a part of the swagger-codegen project? Because:
- I don't really know java very well and so I'd be learning both java and the object model of the codegen which was in heavy flux as opposed to doing go and I really wanted to go experience of designing a large codebase with it.
- Go's super limited type system makes it so that it doesn't fit well in the model of swagger-codegen
- Go's idea of polymorphism doesn't reconcile very well with a solution designed for languages that actually have inheritance and so forth.
- For supporting types like
[][][]map[string][][]int64I don't think it's possible with mustacheI gravely underestimated the amount of work that would be involved in making something useful out of it. My personal mission: I want the jvm to go away, it was great way back when now it's just silly (vm in container on vm in vm in container)
What's inside?
Here is an outline of available features (see the full list here):
- An object model that serializes swagger-compliant yaml or json
- A tool to work with swagger
- Serve swagger UI for any swagger spec file
- Flexible code generation, with customizable templates
- Generate go API server based on swagger spec
- Generate go API client from a swagger spec
- Validate a swagger spec document, with extra rules outlined here
- Generate a spec document based on annotated code
- A runtime to work with Rest API and middlewares
- Serve spec
- Routing
- Validation
- Authorization
- Swagger docs UI
There is more to that...
- A typed JSON Schema implementation, supporting most Draft 4 features
- Extended string and numeric formats: strfmt
- Utilities to work with JSON, convert data types and pointers: swag
- A jsonschema (Draft 4) validator, with full $ref support: validate
- Custom validation interface
Installing
go-swagger is available as binary or docker releases as well as from source: more details.
Use-cases
The main package of the toolkit, go-swagger/go-swagger, provides command line tools to help working with swagger.
The toolkit is highly customizable and allows endless possibilities to work with OpenAPI2.0 specifications.
Beside the go-swagger CLI tool and generator, the go-openapi packages provide modular functionality to build custom solutions on top of OpenAPI.
The CLI supports shell autocompletion utilities: see here.
Serve specification UI
Most basic use-case: serve a UI for your spec:
swagger serve https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json
Validate a specification
To validate a Swagger specification:
swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json
Generate an API server
To generate a server for a swagger spec document:
swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]]
Generate an API client
To generate a client for a swagger spec document:
swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]]
Generate a spec from source
To generate a swagger spec document for a go application:
swagger generate spec -o ./swagger.json
Generate a data model
To generate model structures and validators exposed by the API:
swagger generate model --spec={spec}
Transform specs
There are several commands allowing you to transform your spec.
Resolve and expand $ref's in your spec as inline definitions:
swagger expand {spec}
Flatten your spec: all external $ref's are imported into the main document and inline schemas reorganized as definitions.
swagger flatten {spec}
Merge specifications (composition):
swagger mixin {spec1} {spec2}
Licensing
The toolkit itself is licensed as Apache Software License 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.
Who is using this project?
To name but a few... (feel free to sign in there if you are using this project):
In the list below, we tried to figure out the public repos where you'll find examples on how to use
go-swaggerandgo-openapi:
3DSIM
Alibaba PouchAPI
CheckR
Cilium
CoreOS
DigitalOcean
EVE Central
Iron.io
JaegerTracing
Kubernetes-Helm
Kubernetes
ManifoldCo
Metaparticle.io
Netlify
Nutanix
OAS2
OVH API
RackHD
ScaleFT
StratoScale
VMWare
...
Note to users migrating from older releases
Using 0.5.0
Because 0.5.0 and master have diverged significantly, you should checkout the tag 0.5.0 for go-swagger when you use the currently released version.
Migrating from 0.5.0 to 0.6.0
You will have to rename some imports:
github.com/go-swagger/go-swagger/httpkit/validate to github.com/go-openapi/validate
github.com/go-swagger/go-swagger/httpkit to github.com/go-openapi/runtime
github.com/naoina/denco to github.com/go-openapi/runtime/middleware/denco
github.com/go-swagger/go-swagger to github.com/go-openapi
Migrating from 0.12 to 0.13
Spec flattening and $ref resolution brought breaking changes in model generation, since all complex things generate their own definitions.
Migrating from 0.14 to 0.15
Generated servers no more import the following package (replaced by go1.8 native functionality):
github.com/tylerb/graceful
Spec flattening now defaults to minimal changes to models and should be workable for 0.12 users.
Users who prefer to stick to 0.13 and 0.14 default flattening mode may now use the --with-flatten=full option.
Note that the --skip-flatten option has been phased out and replaced by the more explicit --with-expand option.
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 get -u github.com/go-swagger/go-swagger/cmd/swagger
The implementation also provides a number of command line tools to help working with swagger.
Currently there is a spec validator tool:
swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/master/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]]
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
swagger
command
|
|
|
examples
|
|
|
2.0/petstore/server
command
|
|
|
authentication/restapi
Package restapi keyauth debug Schemes: http Host: localhost BasePath: /api Version: 0.3.0 Consumes: - application/keyauth.api.v1+json Produces: - application/keyauth.api.v1+json swagger:meta
|
Package restapi keyauth debug Schemes: http Host: localhost BasePath: /api Version: 0.3.0 Consumes: - application/keyauth.api.v1+json Produces: - application/keyauth.api.v1+json swagger:meta |
|
composed-auth/restapi
Package restapi Composing authorizations This sample API demonstrates how to compose several authentication schemes and configure complex security requirements for your operations.
|
Package restapi Composing authorizations This sample API demonstrates how to compose several authentication schemes and configure complex security requirements for your operations. |
|
contributed-templates/stratoscale/restapi
Package restapi Petstore This is a sample server Petstore server.
|
Package restapi Petstore This is a sample server Petstore server. |
|
generated/cmd/petstore-server
command
|
|
|
generated/restapi
Package restapi Swagger Petstore This is a sample server Petstore server.
|
Package restapi Swagger Petstore This is a sample server Petstore server. |
|
oauth2/cmd/oauth-sample-server
command
|
|
|
oauth2/restapi
Package restapi oauth2 debug Schemes: http Host: localhost BasePath: /api Version: 0.3.0 Consumes: - application/json Produces: - application/json swagger:meta
|
Package restapi oauth2 debug Schemes: http Host: localhost BasePath: /api Version: 0.3.0 Consumes: - application/json Produces: - application/json swagger:meta |
|
stream-server/restapi
Package restapi Countdown Example server for emitting newline delimited JSON Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/json Produces: - application/json swagger:meta
|
Package restapi Countdown Example server for emitting newline delimited JSON Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/json Produces: - application/json swagger:meta |
|
task-tracker/restapi
Package restapi Issue Tracker API This application implements a very simple issue tracker.
|
Package restapi Issue Tracker API This application implements a very simple issue tracker. |
|
todo-list/cmd/todo-list-server
command
|
|
|
todo-list/restapi
Package restapi Simple To Do List API Schemes: http https Host: localhost BasePath: / Version: 0.1.0 Consumes: - application/io.swagger.examples.todo-list.v1+json Produces: - application/io.swagger.examples.todo-list.v1+json swagger:meta
|
Package restapi Simple To Do List API Schemes: http https Host: localhost BasePath: / Version: 0.1.0 Consumes: - application/io.swagger.examples.todo-list.v1+json Produces: - application/io.swagger.examples.todo-list.v1+json swagger:meta |
|
tutorials/custom-server/gen/restapi
Package restapi Greeting Server Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/json Produces: - text/plain swagger:meta
|
Package restapi Greeting Server Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/json Produces: - text/plain swagger:meta |
|
tutorials/todo-list/dynamic-1
command
|
|
|
tutorials/todo-list/server-1/restapi
Package restapi A To Do list application The product of a tutorial on goswagger.io Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/io.goswagger.examples.todo-list.v1+json Produces: - application/io.goswagger.examples.todo-list.v1+json swagger:meta
|
Package restapi A To Do list application The product of a tutorial on goswagger.io Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/io.goswagger.examples.todo-list.v1+json Produces: - application/io.goswagger.examples.todo-list.v1+json swagger:meta |
|
tutorials/todo-list/server-2/restapi
Package restapi A To Do list application The product of a tutorial on goswagger.io Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/io.goswagger.examples.todo-list.v1+json Produces: - application/io.goswagger.examples.todo-list.v1+json swagger:meta
|
Package restapi A To Do list application The product of a tutorial on goswagger.io Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/io.goswagger.examples.todo-list.v1+json Produces: - application/io.goswagger.examples.todo-list.v1+json swagger:meta |
|
tutorials/todo-list/server-complete/restapi
Package restapi A To Do list application The product of a tutorial on goswagger.io Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/io.goswagger.examples.todo-list.v1+json Produces: - application/io.goswagger.examples.todo-list.v1+json swagger:meta
|
Package restapi A To Do list application The product of a tutorial on goswagger.io Schemes: http Host: localhost BasePath: / Version: 1.0.0 Consumes: - application/io.goswagger.examples.todo-list.v1+json Produces: - application/io.goswagger.examples.todo-list.v1+json swagger:meta |
|
fixtures
|
|
|
enhancements/793
Package petstore API The purpose of this application is to provie an application that is using plain go to define an API.
|
Package petstore API The purpose of this application is to provie an application that is using plain go to define an API. |
|
goparsing/bookings
Package booking API.
|
Package booking API. |
|
goparsing/classification
Package classification Petstore API.
|
Package classification Petstore API. |
|
goparsing/invalid_model_param
command
|
|
|
goparsing/invalid_model_response
command
|
|
|
goparsing/invalid_param_model
command
|
|
|
goparsing/invalid_response_model
command
|
|
|
goparsing/petstore
Package petstore Petstore API.
|
Package petstore Petstore API. |
|
goparsing/spec
Package booking API.
|
Package booking API. |
|
Package generator provides the code generation library for go-swagger.
|
Package generator provides the code generation library for go-swagger. |
|
Package scan provides a scanner for go files that produces a swagger spec document.
|
Package scan provides a scanner for go files that produces a swagger spec document. |