Automatic API generation via go-restful

Partially addresses #1052.

There's lots more work left to do here, but I got this working, so I thought I'd share it.

go-restful provides a more structured handler registration mechanism, with the ability to document a number of aspects of the API. The object definitions are extracted via reflection and their descriptions are extracted from field tags (added by the author of go-restful upon my request). It uses https://github.com/swagger-api/swagger-ui for the doc UI, and also provides a discovery API that can be used to query available endpoints and json schemas.

In order for the initial version of this to be merged, two main things need to be done:
1. Fix apiserver_test and make all the tests pass
2. Update and merge the PR that adds go-restful to Godeps

Beyond that, I'd like to iterate on cleaning this up and adding documentation in other PRs:
* Customize the swagger UI for our needs
* Figure out how to copy https://github.com/swagger-api/swagger-ui/dist to the master
* Figure out what to do with the custom verbs (watch, proxy, redirect)
* Convert all handlers to native go-restful style
* Convert handler parameters to go-restful parameters
* Perhaps split REST handlers into per-verb handlers
* Add descriptions to all handlers
* Add description tags to all types.go object fields
* Add documentation of other details (return codes, input/output mime types, etc.)
* Fix go-restful bugs

/cc @lavalamp @smarterclayton @erictune 
Maybe we need a cleanup week.


> On Nov 13, 2014, at 3:48 PM, Daniel Smith <notifications@github.com> wrote:
> 
> In pkg/apiserver/apiserver.go:
> 
> > +	// create one for the tests, also
> > +	// Success:
> > +	// http.StatusOK, http.StatusCreated, http.StatusAccepted, http.StatusNoContent
> > +	//
> > +	// test/integration/auth_test.go is currently the most comprehensive status code test
> > +
> > +	// TODO: eliminate all the restful wrappers
> > +	// TODO: create a separate handler per verb
> > +	h := func(req *restful.Request, resp *restful.Response) {
> > +		glog.V(3).Infof("User-Agent: %s\n", req.HeaderParameter("User-Agent"))
> > +		strippedHandler.ServeHTTP(resp.ResponseWriter, req.Request)
> > +	}
> > +
> > +	// TODO: factor out per-kind code
> > +	for path, storage := range g.handler.storage {
> > +		glog.V(3).Infof("Installing /%s/%s\n", version, path)
> From a readability standpoint, I think it would be great if the body of this loop were moved into its own function, e.g., installSingleHandler or some such. I'm ok merging without this if it will get cleaned up soon, although I'm feeling like in general promised cleanup has not been happening at the promised rate and I'm getting reluctant to say things like this...
> 
> —
> Reply to this email directly or view it on GitHub.
>