GoogleCloudPlatform/kubernetes — pull request #2282 by bgrant0607 (2014-11-11 07:33:17+00:00)
Title: WIP: Automatic API generation via go-restful

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, four 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
3. Customize the swagger UI for our needs
4. Figure out how to copy https://github.com/swagger-api/swagger-ui/dist to the master

Beyond that, I'd like to iterate on cleaning this up and adding documentation in other PRs:
* 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.)

/cc @lavalamp @smarterclayton @erictune