We've been working diligently on the TO Golang Rewrite <https://github.com/apache/incubator-trafficcontrol/projects/2> project to obviously rewrite the Perl into Go, but also to improve our Testing and Documentation efforts. I presented the idea of using Swagger several summits (years) ago about using Swagger to help drive our Traffic Ops API documentation. Since then Swagger has evolved and is becoming the de facto standard for building (the potential for generating TO Golang Client and Server stubs is now available) and documenting REST APIs.
I would like to propose going forward that we use Swagger for future API level documentation (because it can be generated out of our Golang code/structs). The below resources point out a TO API version 1.3 (the version we decided to rev for the rewritten Golang endpoints). The intent behind 1.3 is obviously an improved version of the API (entirely backward compatible to 1.2), but also to give us a starting point for building the API doc in Swagger. The following resources are my examples: Swagger has several implementations and I chose go-swagger <https://github.com/go-swagger/go-swagger> because it has more Golang features. *Sample TO API doc * https://app.swaggerhub.com/apis/dewrich/traffic-ops_api/1.3 *Sample TO Golang code with embedded doc* Generated from the combination of these Golang documentation "hooks" (there's current a go-swagger bug that prevents the doc from being tied directly into the handlers) https://github.com/dewrich/incubator-trafficcontrol/tree/swagger-demo/traffic_ops/traffic_ops_golang/docs And the *asns.go*, *cdns.go*, *divisions.go*, *regions.go* and *statuses.go* structs in my branch here: https://github.com/dewrich/incubator-trafficcontrol/tree/swagger-demo/lib/go-tc *TO Client Generated from Swagger* This new Golang package is only a sample of a TO client generated (based upon the the code generated swagger.json <http://swagger.https://github.com/dewrich/incubator-trafficcontrol/blob/swagger-demo/traffic_ops/traffic_ops_golang/docs/swagger.json> ) https://github.com/dewrich/incubator-trafficcontrol/tree/swagger-demo/traffic_ops/traffic_ops_golang/toclient https://github.com/dewrich/incubator-trafficcontrol/tree/swagger-demo/traffic_ops/traffic_ops_golang/toclient/main.go The hope with tying the documentation closer to the code will help with keeping the API docs up-to-date, as well as providing more documentation for developers. Please give your thoughts on this idea as well as a vote by Feb 21 (a week from today) so that we can move forward with building our TO API doc. -Dew
