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]]
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
swagger/commands/internal/cmdtest
Package cmdtest provides test utilities to assert the output of CLI commands
|
Package cmdtest provides test utilities to assert the output of CLI commands |
Package codescan provides a scanner for go files that produces a swagger spec document.
|
Package codescan provides a scanner for go files that produces a swagger spec document. |
examples
|
|
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. |
external-types/restapi
Package restapi external types imports: external anonymous types This sample specification exercises external types, with both x-go-type in definitions and inlined.
|
Package restapi external types imports: external anonymous types This sample specification exercises external types, with both x-go-type in definitions and inlined. |
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/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-strict/restapi
Package restapi Simple To Do List API This is a simple todo list API illustrating go-swagger codegen capabilities.
|
Package restapi Simple To Do List API This is a simple todo list API illustrating go-swagger codegen capabilities. |
todo-list/restapi
Package restapi Simple To Do List API This is a simple todo list API illustrating go-swagger codegen capabilities.
|
Package restapi Simple To Do List API This is a simple todo list API illustrating go-swagger codegen capabilities. |
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/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/meta/v1
Package meta Petstore API.
|
Package meta Petstore API. |
goparsing/meta/v2
Package meta Petstore API.
|
Package meta Petstore API. |
goparsing/meta/v3
Package meta Petstore API.
|
Package meta Petstore API. |
goparsing/meta/v4
Package meta Petstore API.
|
Package meta Petstore API. |
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. |