swagger

package module
v0.0.0-...-220a68f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 9, 2017 License: Apache-2.0 Imports: 0 Imported by: 0

README

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

Contains an implementation of Swagger 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)

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

Docs

https://goswagger.io

Binary distribution

go-swagger is distributed as binaries that are built of 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
Debian packages Download

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
RPM packages Download

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
From source

Install or update from source:

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
Bash Completion

Bash completion is supported and can be activated as follows:

source ./cmd/swagger/completion/swagger.bash-completion

Note that this does require you already setup bash completion, which can be done in 2 simple steps:

  1. install bash-completion using your favourite package manager;

  2. run source /etc/bash_completion in bash;

Zsh Completion

Zsh completion is supported and can be copied/soft-linked from:

./cmd/swagger/completion/swagger.zsh-completion

In case you're new to adding auto-completion to zsh completion, here is how you could enable swagger's zsh completion step by step:

  1. create a folder used to store your completions (eg. $HOME/.zsh/completion);

  2. append the following to your $HOME/.zshrc file:

# add auto-completion directory to zsh's fpath
fpath=($HOME/.zsh/completion $fpath)

# compsys initiatlization
autoload -U compinit
compinit
  1. copy/soft-link ./cmd/swagger/completion/swagger.zsh-completion to $HOME/.zsh/completion/_swagger;

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.

What's inside?

For a V1 I want to have this feature set completed:

  • Documentation site

  • Play nice with golint, go vet etc.

  • An object model that serializes to swagger yaml or json

  • A tool to work with swagger:

    • validate a swagger spec document:

    • validate against jsonschema

    • validate extra rules outlined here

      • definition can't declare a property that's already defined by one of its ancestors (Error)
      • definition's ancestor can't be a descendant of the same model (Error)
      • each api path should be non-verbatim (account for path param names) unique per method (Error)
      • each security reference should contain only unique scopes (Warning)
      • each path parameter should correspond to a parameter placeholder and vice versa (Error)
      • path parameter declarations do not allow empty names (/path/{} is not valid) (Error)
      • each definition property listed in the required array must be defined in the properties of the model (Error)
      • each parameter should have a unique name and in combination (Error)
      • each operation should have at most 1 parameter of type body (Error)
      • each operation cannot have both a body parameter and a formData parameter (Error)
      • each operation must have an unique operationId (Error)
      • each reference must point to a valid object (Error)
      • each referencable definition must have references (Warning)
      • every default value that is specified must validate against the schema for that property (Error)
      • every example that is specified must validate against the schema for that property (Error)
      • items property is required for all schemas/definitions of type array (Error)
    • serve swagger UI for any swagger spec file

    • code generation

    • generate api based on swagger spec

    • generate go client from a swagger spec

    • spec generation

    • generate spec document based on the code

      • generate meta data (top level swagger properties) from package docs
      • generate definition entries for models
      • support composed structs out of several embeds
      • support allOf for composed structs
      • generate path entries for routes
      • generate responses from structs
      • support composed structs out of several embeds
      • generate parameters from structs
      • support composed structs out of several embeds
  • Middlewares:

    • serve spec

    • routing

    • validation

    • additional validation through an interface

    • authorization

      • basic auth
      • api key auth
      • oauth2 bearer auth
    • swagger docs UI

  • Typed JSON Schema implementation

    • JSON Pointer that knows about structs
    • JSON Reference that knows about structs
    • Passes current json schema test suite
  • extended string formats

    • uuid, uuid3, uuid4, uuid5
    • email
    • uri (absolute)
    • hostname
    • ipv4
    • ipv6
    • mac
    • credit card
    • isbn, isbn10, isbn13
    • social security number
    • hexcolor
    • rgbcolor
    • date
    • date-time
    • duration
    • password
    • custom string formats

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.

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
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
generated/restapi
Package restapi Swagger Petstore This is a sample server Petstore server.
Package restapi Swagger Petstore This is a sample server Petstore server.
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/restapi
Package restapi Simple To Do List API Schemes: http https Host: localhost BasePath: / Version: 0.1.0 Consumes: - application/io.swagger.examples.todo-list.v1+json Produces: - application/io.swagger.examples.todo-list.v1+json swagger:meta
Package restapi Simple To Do List API Schemes: http https Host: localhost BasePath: / Version: 0.1.0 Consumes: - application/io.swagger.examples.todo-list.v1+json Produces: - application/io.swagger.examples.todo-list.v1+json swagger:meta
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/petstore
Package petstore Petstore API.
Package petstore Petstore API.
Package generator provides the code generation library for go-swagger The general idea is that you should rarely see interface{} in the generated code.
Package generator provides the code generation library for go-swagger The general idea is that you should rarely see interface{} in the generated code.
Package scan provides a scanner for go files that produces a swagger spec document.
Package scan provides a scanner for go files that produces a swagger spec document.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL