github.com/go-swagger/go-swagger@v0.31.0/docs/_index.md (about) 1 --- 2 title: README 3 date: 2023-01-01T01:01:01-08:00 4 draft: true 5 weight: 1 6 --- 7 {{<forkme url="https://github.com/go-swagger/go-swagger/fork">}} 8 9 {{< hint "info" >}} 10 {{< param goswagger.versionMessage >}} 11 {{< /hint >}} 12 13 # Swagger 2.0 [](https://github.com/go-swagger/go-swagger/actions/workflows/test.yaml) [](https://codecov.io/gh/go-swagger/go-swagger)[](https://goreportcard.com/report/github.com/go-swagger/go-swagger) 14 15 [](https://badge.fury.io/gh/go-swagger%2Fgo-swagger) [](https://quay.io/repository/goswagger/swagger?tab=tags) [](https://github.com/orgs/go-swagger/packages/container/go-swagger/versions)  16 17 [](https://slackin.goswagger.io) 18 [](https://raw.githubusercontent.com/swagger-api/swagger-spec/master/LICENSE) 19 [](http://godoc.org/github.com/go-swagger/go-swagger) 20 21 [](https://securityscorecards.dev/viewer/?uri=github.com/go-swagger/go-swagger) 22 [](https://app.fossa.io/projects/git%2Bgithub.com%2Fgo-swagger%2Fgo-swagger?ref=badge_shield) 23 24 --- 25 26 This project contains a golang implementation of Swagger 2.0 (aka [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)). 27 It provide tools to work with swagger specifications. 28 29 [Swagger](https://swagger.io/) is a simple yet powerful representation of your RESTful API.<br> 30 31 >  **Swagger in a nutshell** 32 > 33 > 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. 34 > 35 > With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. We created Swagger to help fulfill the promise of APIs. 36 > 37 > 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. 38 39 ## Features 40 `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. 41 42 * Generates a server from a swagger specification 43 * Generates a client from a swagger specification 44 * Generates a CLI (command line tool) from a swagger specification (alpha stage) 45 * Supports most features offered by jsonschema and swagger, including polymorphism 46 * Generates a swagger specification from annotated go code 47 * Additional tools to work with a swagger spec 48 * Great customization features, with vendor extensions and customizable templates 49 50 Our focus with code generation is to produce idiomatic, fast go code, which plays nice with golint, go vet etc. 51 52 ## Project status 53 This project supports OpenAPI 2.0. **At this moment it does not support OpenAPI 3.x**. 54 55 `go-swagger` is now feature complete and has stabilized its API. 56 57 Most features and building blocks are now in a stable state, with a rich set of CI tests. 58 59 The go-openapi community actively continues bringing fixes and enhancements to this code base. 60 61 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). 62 63 ## How is this different from go generator in swagger-codegen? 64 **tl;dr** The main difference at this moment is that this one actually works... 65 66 The swagger-codegen project only generates a _workable_ go client and even there it will only support flat models. 67 Further, the go server generated by swagger-codegen is mostly a stub. 68 69 > **Motivation** (by [@casualjim](github.com/casualjim)) 70 > Why is this not done as a part of the swagger-codegen project? Because: 71 > 72 > * 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. 73 > * Go's super limited type system makes it so that it doesn't fit well in the model of swagger-codegen 74 > * Go's idea of polymorphism doesn't reconcile very well with a solution designed for languages that actually have inheritance and so forth. 75 > * For supporting types like `[][][]map[string][][]int64` I don't think it's possible with mustache 76 > 77 > I gravely underestimated the amount of work that would be involved in making something useful out of it. 78 > 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) 79 80 ## What's inside? 81 82 Here is an outline of available features (see the full list [here](features.md)): 83 84 - An object model that serializes swagger-compliant yaml or json 85 - A tool to work with swagger 86 - Serve swagger UI for any swagger spec file 87 - Flexible code generation, with customizable templates 88 - Generate go API server based on swagger spec 89 - Generate go API client from a swagger spec 90 - Validate a swagger spec document, with extra rules outlined [here](https://github.com/apigee-127/sway/blob/master/docs/README.md#semantic-validation) 91 - Generate a spec document based on annotated code 92 - A runtime to work with Rest API and middlewares 93 - Serve spec 94 - Routing 95 - Validation 96 - Authorization 97 - Swagger docs UI 98 - A Diff tool which will cause a build to fail if a change in the spec breaks backwards compatibility 99 100 There is more to that... 101 102 - A [typed JSON Schema implementation](reference/models), supporting most Draft 4 features 103 - Extended string and numeric formats: [strfmt](https://github.com/go-openapi/strfmt) 104 - Utilities to work with JSON, convert data types and pointers: [swag](https://github.com/go-openapi/swag) 105 - A jsonschema (Draft 4) validator, with full $ref support: [validate](https://github.com/go-openapi/validate) 106 - Custom validation interface 107 108 ## Use-cases 109 The main package of the toolkit, go-swagger/go-swagger, provides command line tools to help working with swagger. 110 111 The toolkit is highly customizable and allows endless possibilities to work with OpenAPI2.0 specifications. 112 113 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. 114 115 The CLI supports shell autocompletion utilities: see [here](usage/cli_helpers.md). 116 117 ### Serve specification UI 118 Most basic use-case: serve a UI for your spec: 119 120 ``` 121 swagger serve https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json 122 ``` 123 124 ### Validate a specification 125 To [validate](usage/validate.md) a Swagger specification: 126 127 ``` 128 swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json 129 ``` 130 131 ### Generate an API server 132 To generate a [server for a swagger spec](generate/server.md) document: 133 134 ``` 135 swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]] 136 ``` 137 138 ### Generate an API client 139 To generate a [client for a swagger spec](generate/client.md) document: 140 141 ``` 142 swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]] 143 ``` 144 ### Generate an CLI (Command line tool) 145 To generate a [CLI for a swagger spec](https://github.com/go-swagger/go-swagger/tree/master/examples/cli) document: 146 ``` 147 swagger generate cli [-f ./swagger.json] -A [application-name [--principal [principal-name]] 148 ``` 149 ### Generate a spec from source 150 To generate a [swagger spec document for a go application](generate-spec/spec.md): 151 152 ``` 153 swagger generate spec -o ./swagger.json 154 ``` 155 156 ### Generate a data model 157 To generate model structures and validators exposed by the API: 158 159 ``` 160 swagger generate model --spec={spec} 161 ``` 162 163 ### Transform specs 164 165 There are [several commands](reference/transform) allowing you to transform your spec. 166 167 Resolve and expand $ref's in your spec as inline definitions: 168 ``` 169 swagger expand {spec} 170 ``` 171 172 Flatten your spec: all external $ref's are imported into the main document and inline schemas reorganized as definitions. 173 ``` 174 swagger flatten {spec} 175 ``` 176 177 Merge specifications (composition): 178 ``` 179 swagger mixin {spec1} {spec2} 180 ``` 181 182 ### Compare specs 183 184 The diff command allows you to check backwards compatibility. 185 Type ```swagger diff --help``` for info. 186 187 ``` 188 swagger diff {spec1} {spec2} 189 ``` 190 191 ### Generate spec markdown spec 192 193 ``` 194 swagger generate markdown -f {spec} --output swagger.mode 195 ``` 196 197 ## Try it 198 199 Try `go-swagger` in a free online workspace using Gitpod: 200 201 [](https://gitpod.io#https://github.com/go-swagger/go-swagger) 202 203 ## Licensing 204 205 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. 206 207 ### Licence scan on dependencies 208 [](https://app.fossa.io/projects/git%2Bgithub.com%2Fgo-swagger%2Fgo-swagger?ref=badge_large) 209 210 ## Who is using this project? 211 212 To name but a few... (feel free to sign in there if you are using this project): 213 214 > 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`: 215 216 [3DSIM](https://github.com/3DSIM) 217 [Alibaba PouchAPI](https://github.com/alibaba/pouch) 218 [CheckR](https://github.com/checkr/flagr) 219 [Cilium](https://github.com/cilium/cilium) 220 [CoreOS](https://github.com/coreos/go-quay) 221 [NetBox Community](https://github.com/netbox-community/go-netbox) 222 [EVE Central](https://github.com/evecentral) 223 Iron.io 224 [JaegerTracing](https://github.com/jaegertracing/jaeger) 225 [Kubernetes-Helm](https://github.com/kubernetes-helm/monocular) 226 [Kubernetes](https://godoc.org/k8s.io/apiextensions-apiserver/pkg/apiserver) 227 [ManifoldCo](https://github.com/manifoldco) 228 [Metaparticle.io](https://github.com/metaparticle-io/metaparticle-ast) 229 [Netlify](https://github.com/netlify/open-api) 230 [Nutanix](https://github.com/nutanix) 231 [OAS2](https://github.com/hypnoglow/oas2) 232 [OVH API](https://github.com/appscode/go-ovh) 233 [RackHD](https://github.com/RackHD/RackHD) 234 [ScaleFT](https://github.com/authclub/billforward) 235 [StratoScale](https://github.com/Stratoscale/swagger) 236 [Terraform Provider OpenAPI](https://github.com/dikhan/terraform-provider-openapi) 237 [VMware](https://github.com/vmware/dispatch) 238 ... 239 240 ## Note to users migrating from older releases 241 242 ### Migrating from 0.25 to [master] 243 244 Changes in the behavior of the generated client regarding defaults in parameters and response headers: 245 246 * default values for parameters are no more hydrated by default and sent over the wire 247 (assuming the server uses defaults). 248 * the previous behavior (explicitly sending defaults over the wire) can be obtained 249 with the SetDefaults() and WithDefaults() parameter methods. 250 * the body parameter is not pre-hydrated with the default from it schema 251 * default values for response headers are hydrated when the header is not received 252 (previously, headers remained with their zero value) 253 254 ### Migrating from 0.24 to 0.25 255 256 The options for `generate model --all-definitions` and `--skip-struct` are marked for deprecation. 257 258 For now, the CLI continues to accept these options. They will be removed in a future version. 259 260 Generating all definitions is now the default behavior when no other option filters the generation scope. 261 The `--skip-struct` option had no effect. 262 263 ### Migrating from 0.14 to 0.15 264 265 Generated servers no more import the following package (replaced by go1.8 native functionality): 266 ``` 267 github.com/tylerb/graceful 268 ``` 269 270 Spec flattening now defaults to minimal changes to models and should be workable for 0.12 users. 271 272 Users who prefer to stick to 0.13 and 0.14 default flattening mode may now use the `--with-flatten=full` option. 273 274 Note that the `--skip-flatten` option has been phased out and replaced by the more explicit `--with-expand` option. 275 276 ### Migrating from 0.12 to 0.13 277 278 Spec flattening and $ref resolution brought breaking changes in model generation, since all complex things generate their own definitions. 279 280 ### Migrating from 0.5.0 to 0.6.0 281 282 You will have to rename some imports: 283 284 ``` 285 github.com/go-swagger/go-swagger/httpkit/validate to github.com/go-openapi/validate 286 github.com/go-swagger/go-swagger/httpkit to github.com/go-openapi/runtime 287 github.com/naoina/denco to github.com/go-openapi/runtime/middleware/denco 288 github.com/go-swagger/go-swagger to github.com/go-openapi 289 ``` 290 291 ### Using 0.5.0 292 293 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.