github.com/hsdp/go-swagger@v0.19.0/docs/README.md (about) 1 # Swagger 2.0 [](https://circleci.com/gh/go-swagger/go-swagger) [](https://ci.appveyor.com/project/casualjim/go-swagger/branch/master) [](https://codecov.io/gh/go-swagger/go-swagger) [](https://badge.fury.io/gh/go-swagger%2Fgo-swagger) 2 [](https://slackin.goswagger.io) 3 [](https://raw.githubusercontent.com/swagger-api/swagger-spec/master/LICENSE) 4 [](http://godoc.org/github.com/go-swagger/go-swagger) 5 [](https://quay.io/repository/goswagger/swagger) 6 [](https://app.fossa.io/projects/git%2Bgithub.com%2Fgo-swagger%2Fgo-swagger?ref=badge_shield) 7 [](https://golangci.com) 8 [](https://goreportcard.com/report/github.com/go-swagger/go-swagger) 9 10 This package contains a golang implementation of Swagger 2.0 (aka [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)): 11 it knows how to serialize and deserialize swagger specifications. 12 13 [Swagger](https://swagger.io/) is a simple yet powerful representation of your RESTful API.<br> 14 15 >  **Swagger in a nutshell** 16 > 17 > 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. 18 > 19 > With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. We created Swagger to help fulfill the promise of APIs. 20 > 21 > 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. 22 23 ## Features 24 `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. 25 26 * Generates a server from a swagger specification 27 * Generates a client from a swagger specification 28 * Supports most features offered by jsonschema and swagger, including polymorphism 29 * Generates a swagger specification from annotated go code 30 * Additional tools to work with a swagger spec 31 * Great customization features, with vendor extensions and customizable templates 32 33 Our focus with code generation is to produce idiomatic, fast go code, which plays nice with golint, go vet etc. 34 35 ## Project status 36 `go-swagger` is now feature complete and has stabilized its API. 37 38 Most features and building blocks are now in a stable state, with a rich set of CI tests. 39 40 The go-openapi community actively continues bringing fixes and enhancements to this code base. 41 42 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](https://slackin.goswagger.io). 43 44 ## Documentation 45 <https://goswagger.io> 46 47 ## FAQ 48 Q&A contributed by the community: 49 50 <https://goswagger.io/faq/> 51 52 ## How is this different from go generator in swagger-codegen? 53 **tl;dr** The main difference at this moment is that this one actually works... 54 55 The swagger-codegen project only generates a _workable_ go client and even there it will only support flat models. 56 Further, the go server generated by swagger-codegen is mostly a stub. 57 58 > **Motivation** 59 > Why is this not done as a part of the swagger-codegen project? Because: 60 > 61 > * 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. 62 > * Go's super limited type system makes it so that it doesn't fit well in the model of swagger-codegen 63 > * Go's idea of polymorphism doesn't reconcile very well with a solution designed for languages that actually have inheritance and so forth. 64 > * For supporting types like `[][][]map[string][][]int64` I don't think it's possible with mustache 65 > 66 > I gravely underestimated the amount of work that would be involved in making something useful out of it. 67 > 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) 68 69 ## What's inside? 70 71 Here is an outline of available features (see the full list [here](https://goswagger.io/features.html)): 72 73 - An object model that serializes swagger-compliant yaml or json 74 - A tool to work with swagger 75 - Serve swagger UI for any swagger spec file 76 - Flexible code generation, with customizable templates 77 - Generate go API server based on swagger spec 78 - Generate go API client from a swagger spec 79 - Validate a swagger spec document, with extra rules outlined [here](https://github.com/apigee-127/sway/blob/master/docs/README.md#semantic-validation) 80 - Generate a spec document based on annotated code 81 - A runtime to work with Rest API and middlewares 82 - Serve spec 83 - Routing 84 - Validation 85 - Authorization 86 - Swagger docs UI 87 88 There is more to that... 89 90 - A [typed JSON Schema implementation](https://goswagger.io/use/model.html), supporting most Draft 4 features 91 - Extended string and numeric formats: [strfmt](https://github.com/go-openapi/strfmt) 92 - Utilities to work with JSON, convert data types and pointers: [swag](https://github.com/go-openapi/swag) 93 - A jsonschema (Draft 4) validator, with full $ref support: [validate](https://github.com/go-openapi/validate) 94 - Custom validation interface 95 96 ## Installing 97 `go-swagger` is available as binary or docker releases as well as from source: [more details](https://goswagger.io/install.html). 98 99 ## Use-cases 100 The main package of the toolkit, go-swagger/go-swagger, provides command line tools to help working with swagger. 101 102 The toolkit is highly customizable and allows endless possibilities to work with OpenAPI2.0 specifications. 103 104 Beside the go-swagger CLI tool and generator, the [go-openapi packages](https://github.com/go-openapi) provide modular functionality to build custom solutions on top of OpenAPI. 105 106 The CLI supports shell autocompletion utilities: see [here](https://goswagger.io/cli_helpers.html). 107 108 ### Serve specification UI 109 Most basic use-case: serve a UI for your spec: 110 111 ``` 112 swagger serve https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json 113 ``` 114 115 ### Validate a specification 116 To [validate](https://goswagger.io/usage/validate.html) a Swagger specification: 117 118 ``` 119 swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json 120 ``` 121 122 ### Generate an API server 123 To generate a [server for a swagger spec](https://goswagger.io/generate/server.html) document: 124 125 ``` 126 swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]] 127 ``` 128 129 ### Generate an API client 130 To generate a [client for a swagger spec](https://goswagger.io/generate/client.html) document: 131 132 ``` 133 swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]] 134 ``` 135 136 ### Generate a spec from source 137 To generate a [swagger spec document for a go application](https://goswagger.io/generate/spec.html): 138 139 ``` 140 swagger generate spec -o ./swagger.json 141 ``` 142 143 ### Generate a data model 144 To generate model structures and validators exposed by the API: 145 146 ``` 147 swagger generate model --spec={spec} 148 ``` 149 150 ### Transform specs 151 152 There are [several commands](https://goswagger.io/use/transform.html) allowing you to transform your spec. 153 154 Resolve and expand $ref's in your spec as inline definitions: 155 ``` 156 swagger expand {spec} 157 ``` 158 159 Flatten you spec: all external $ref's are imported into the main document and inline schemas reorganized as definitions. 160 ``` 161 swagger flatten {spec} 162 ``` 163 164 Merge specifications (composition): 165 ``` 166 swagger mixin {spec1} {spec2} 167 ``` 168 169 ## Licensing 170 171 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. 172 173 174 [](https://app.fossa.io/projects/git%2Bgithub.com%2Fgo-swagger%2Fgo-swagger?ref=badge_large) 175 176 ## Who is using this project? 177 178 To name but a few... (feel free to sign in there if you are using this project): 179 180 > In the list below, we tried to figure out the public repos where you'll find examples on how to use `go-swagger` and `go-openapi`: 181 182 [3DSIM](https://github.com/3DSIM) 183 [Alibaba PouchAPI](https://github.com/alibaba/pouch) 184 [CheckR](https://github.com/checkr/flagr) 185 [Cilium](https://github.com/cilium/cilium) 186 [CoreOS](https://github.com/coreos/go-quay) 187 [DigitalOcean](https://github.com/digitalocean/go-netbox) 188 [EVE Central](https://github.com/evecentral) 189 Iron.io 190 [JaegerTracing](https://github.com/jaegertracing/jaeger) 191 [Kubernetes-Helm](https://github.com/kubernetes-helm/monocular) 192 [Kubernetes](https://godoc.org/k8s.io/apiextensions-apiserver/pkg/apiserver) 193 [ManifoldCo](https://github.com/manifoldco) 194 [Metaparticle.io](https://github.com/metaparticle-io/metaparticle-ast) 195 [Netlify](https://github.com/netlify/open-api) 196 [Nutanix](https://github.com/nutanix) 197 [OAS2](https://github.com/hypnoglow/oas2) 198 [OVH API](https://github.com/appscode/go-ovh) 199 [RackHD](https://github.com/RackHD/RackHD) 200 [ScaleFT](https://github.com/authclub/billforward) 201 [StratoScale](https://github.com/Stratoscale/swagger) 202 [VMWare](https://github.com/vmware/dispatch) 203 ... 204 205 ## Note to users migrating from older releases 206 207 ### Using 0.5.0 208 209 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. 210 211 ### Migrating from 0.5.0 to 0.6.0 212 213 You will have to rename some imports: 214 215 ``` 216 github.com/go-swagger/go-swagger/httpkit/validate to github.com/go-openapi/validate 217 github.com/go-swagger/go-swagger/httpkit to github.com/go-openapi/runtime 218 github.com/naoina/denco to github.com/go-openapi/runtime/middleware/denco 219 github.com/go-swagger/go-swagger to github.com/go-openapi 220 ``` 221 222 ### Migrating from 0.12 to 0.13 223 224 Spec flattening and $ref resolution brought breaking changes in model generation, since all complex things generate their own definitions. 225 226 ### Migrating from 0.14 to 0.15 227 228 Generated servers no more import the following package (replaced by go1.8 native functionality): 229 ``` 230 github.com/tylerb/graceful 231 ``` 232 233 Spec flattening now defaults to minimal changes to models and should be workable for 0.12 users. 234 235 Users who prefer to stick to 0.13 and 0.14 default flattening mode may now use the `--with-flatten=full` option. 236 237 Note that the `--skip-flatten` option has been phased out and replaced by the more explicit `--with-expand` option.