go-swagger:用go语言实现Swagger 2.0
go-swagger:用go语言实现Swagger 2.0
Go 其它杂项
共5623Star
详细介绍
Development of this toolkit is sponsored by VMware
Contains an 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.
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.
How is this different from go generator in swagger-codegen?
tl;dr The main difference at this moment is that this one will actually work.
The swagger-codegen project only generates a client and even there it will only support flat models.
- This project supports most features offered by jsonschema including polymorphism.
- It allows for generating a swagger specification from go code.
- It allows for generating a server from a swagger definition and to generate an equivalent spec back from that codebase.
- It allows for generating a client from a swagger definition.
- It has support for several common swagger vendor extensions.
Why is this not done in 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 to 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 API based on swagger spec
- Generate go client from a swagger spec
-
Validate a swagger spec document, with extra rules outlined here
-
Validate against jsonschema (Draft 4), with full $ref support
-
Generate spec document based on annotated code
-
-
Middlewares
- serve spec
- routing
- validation
- additional validation through an interface
- authorization
- swagger docs UI
-
Typed JSON Schema implementation
-
Extended string and numeric formats
-
Project documentation site
-
Play nice with golint, go vet etc.
Documentation
Installing
Installing from binary distributions
go-swagger releases are distributed as binaries that are built from signed tags. It is published as github release, rpm, deb and docker image.
Docker image
docker pull quay.io/goswagger/swagger
alias swagger="docker run --rm -it -v $HOME:$HOME -w $(pwd) quay.io/goswagger/swagger"
swagger version
Homebrew/Linuxbrew
brew tap go-swagger/go-swagger
brew install go-swagger
Static binary
You can download a binary for your platform from github: https://github.com/go-swagger/go-swagger/releases/latest
latestv=$(curl -s https://api.github.com/repos/go-swagger/go-swagger/releases/latest | jq -r .tag_name)
curl -o /usr/local/bin/swagger -L'#' https://github.com/go-swagger/go-swagger/releases/download/$latestv/swagger_$(echo `uname`|tr '[:upper:]' '[:lower:]')_amd64
chmod +x /usr/local/bin/swagger
This repo will work for any debian, the only file it contains gets copied to /usr/bin
echo "deb https://dl.bintray.com/go-swagger/goswagger-debian ubuntu main" | sudo tee -a /etc/apt/sources.list
This repo should work on any distro that wants rpm packages, the only file it contains gets copied to /usr/bin
wget https://bintray.com/go-swagger/goswagger-rpm/rpm -O bintray-go-swagger-goswagger-rpm.repo
Installing from source
Install or update from source:
go get -u github.com/go-swagger/go-swagger/cmd/swagger
Use-cases
The main package of the toolkit, go-swagger/go-swagger, provides a number of 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 spec 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 an OpenAPI 2.0 spec
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
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}
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
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.
FAQ
-
0 Star
-
13 Star
-
0 Star
-
2342 Star
-
0 Star