swugger

README

swugger

This proof-of-concept repo is just here to start a discussion about swagger support for httprouter (and others) based on the swagger support in go-restful/swagger.

In the near future I'd like to create a new repo, forked from go-restful, and stripped back to provide swagger support for other routers.

Background

1. go-restful has support for self-documenting APIs, with Swagger support out of the box. You can even grab a copy of swagger-ui and tell go-restful to serve it. go-restful encourages you to add documentation at the point where you set up routes, which makes for up-to-date documentation. It uses fluent interfaces, which is nice but I don't know if it's 'idiomatic'.
2. httprouter is a high-performance router, which doesnt currently have swagger support. This is true of most of the routers represented in this benchmark, so it might be nice to make swagger functionality available to each of these frameworks.
3. There are some other go-based swagger offerings, but I got the best mileage from go-restful. Please let me know of any others.

swugger

Swugger is a quick and dirty way to show how you might add swagger support to httprouter.

• AFAIK the only way to 'borrow' go-restful's swagger code, is to set up & document 'dummy' routes based on equivalent httprouter routes.
• AFAIK the only way to record routing information in httprouter, is to wrap routing requests inside a 'proxy' function.

So, I just made a package 'swugger' to apply these workarounds and use them in an example.

Installation

go get github.com/laher/swugger/examples/swugger-hello-httprouter

Running the example

swugger-hello-httprouter

This runs a service on localhost:8080.

You can browse to http://localhost:8080/doc/apidocs.json and see the main swagger representation. You can then append /hello to list the methods in the example service itself.

Running swagger-ui

(Approximately, depending on where your gopath is:

git clone https://github.com/wordkik/swagger-ui

Now run the example again such that it will pick up swagger-ui:

cd swagger-ui
swugger-hello-httprouter

Now browse to http://localhost:8080/doc/apidocs/ and put /doc/apidocs.json into the text box, & hit 'Explore'. You can then expand the list of operations & invoke them accordingly.

Next steps

I'll go ahead and start modifying a fork of go-restful/swagger, to do the same thing but without actually setting up dummy routes. I'll also make it more concise than this.

First I'll start a discussion with the creators of both projects, and go from there.

You can use this if you like, but it's not recommended for production use. Cheers.

Documentation

Index

• type HttpRouterSwagger
  • func NewHRS(webServiceAddr string, httpRouter *httprouter.Router) *HttpRouterSwagger
  • func (hrs *HttpRouterSwagger) AddRoute(ws *WebService, method string, path string, function httprouter.Handle, ...) *restful.RouteBuilder
  • func (hrs *HttpRouterSwagger) AddService(path string, serviceDoc ServiceDoc) *WebService
  • func (hrs *HttpRouterSwagger) GetSwaggerHandler() http.Handler
  • func (hrs *HttpRouterSwagger) Init(webServiceAddr string)
  • func (hrs *HttpRouterSwagger) RegisterSwaggerService()
• type MethodDoc
• type ParamDoc
• type ServiceDoc
• type WebService
  • func (ws *WebService) AddRoute(method string, path string, function httprouter.Handle, methodDoc MethodDoc) *restful.RouteBuilder

Types

type HttpRouterSwagger

type HttpRouterSwagger struct {
	HttpRouter         *httprouter.Router
	GoRestfulContainer *restful.Container
	//GoRestfulWebServices []*restful.WebService
	SwaggerConfig *swagger.Config
	// contains filtered or unexported fields
}

func NewHRS

func NewHRS(webServiceAddr string, httpRouter *httprouter.Router) *HttpRouterSwagger

func (*HttpRouterSwagger) AddRoute

func (hrs *HttpRouterSwagger) AddRoute(ws *WebService, method string, path string, function httprouter.Handle, methodDoc MethodDoc) *restful.RouteBuilder

func (*HttpRouterSwagger) AddService

func (hrs *HttpRouterSwagger) AddService(path string, serviceDoc ServiceDoc) *WebService

func (*HttpRouterSwagger) GetSwaggerHandler

func (hrs *HttpRouterSwagger) GetSwaggerHandler() http.Handler

func (*HttpRouterSwagger) Init

func (hrs *HttpRouterSwagger) Init(webServiceAddr string)

Not sure if this should have defaults or not, but it feels like there should be recommended swagger uri accross implementations.

func (*HttpRouterSwagger) RegisterSwaggerService

func (hrs *HttpRouterSwagger) RegisterSwaggerService()

type MethodDoc

type MethodDoc struct {
	Operation string
	Doc       string
	Notes     string
	Params    []ParamDoc
	Reads     interface{}
	Writes    interface{}
}

type ParamDoc

type ParamDoc struct {
	Type     string
	Name     string
	Doc      string
	DataType string
}

type ServiceDoc

type ServiceDoc struct {
	Doc      string
	Consumes []string
	Produces []string
}

type WebService

type WebService struct {
	*restful.WebService
	Hrs  *HttpRouterSwagger
	Path string
}

wrapper for restful.WebService

func (*WebService) AddRoute

func (ws *WebService) AddRoute(method string, path string, function httprouter.Handle, methodDoc MethodDoc) *restful.RouteBuilder