Go Shell PowerShell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci Fix issues on simple params (#1394) Feb 9, 2018
.githooks/pre-commit remove some obsolete files [ci skip] Oct 12, 2016
.github Update ISSUE_TEMPLATE.md Jan 22, 2017
cmd/swagger missing letter in message (possiby => possibly) Apr 24, 2018
docs Update custom-server.md May 15, 2018
examples Fix build deps (#1515) May 4, 2018
fixtures Allow struct fields to be annotated with swagger:ignore May 13, 2018
generator Fix complex anonymous additional properties May 10, 2018
hack Lifts validations (#1507) May 7, 2018
notes prepare for 0.13.0 release Nov 12, 2017
scan Allow struct fields to be annotated with swagger:ignore May 13, 2018
vendor Fix build deps (#1515) May 4, 2018
.dockerignore verifies support of strfmt and nested collections in parameters (#725) Nov 7, 2016
.editorconfig Task: Add Makefile and scripts Apr 13, 2017
.gitignore Corrected Path generation for Base Imports Aug 28, 2017
.hound.yml add hound for minimal linting Feb 15, 2016
CODE_OF_CONDUCT.md update code of conduct to 1.4 version Jan 31, 2016
DCO fixes #65 support discriminators for schemas Nov 29, 2015
Dockerfile update vendor Dec 4, 2017
Dockerfile.ci support file as response schema (#1329) Dec 19, 2017
Dockerfile.dev update vendor Dec 4, 2017
Gopkg.lock Fix build deps (#1515) May 4, 2018
Gopkg.toml migrate from gvt to golang/dep (#1106) Jul 23, 2017
LICENSE adds license header Nov 15, 2015
README.md revamp README May 15, 2018
appveyor.yml Increased test timeout in appveyor to 20m Jan 9, 2018
book.json Add gitbook for docs Jul 31, 2016
design.md Generates fluent builder methods where appropriate Dec 23, 2015
doc.go Acknowledge bug fixes and add CI fixtures. Mar 13, 2018

README.md

Swagger 2.0 Build Status Build status codecov Slack Status

license GoDoc GitHub version Docker Repository on Quay

Development of this toolkit is sponsored by VMware
VMWare

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

Most features and building blocks are now in a stable state.

The go-openapi community actively continues bringing fixes and enhancements to the 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

https://goswagger.io

FAQ

Q&A contributed by the community:

https://goswagger.io/faq/

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][][]int64 I don't think it's possible with mustache

I 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

Resolve and expand $ref's in your spec as inline definitions:

swagger expand {spec}

Flatten you 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-swagger and go-openapi:

3DSIM Alibaba PouchAPI CheckR Cilium CoreOS DigitalOcean EVE Central Iron.io JaegerTracing Kubernetes-Helm Kubernetes ManifoldCo Metaparticle.io Netlify 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