Sounds good. I look forward to seeing it merged into our repo. I guess this means there will need to be a PR to remove our current API docs as they get moved to swagger.
On Tue, Feb 20, 2018 at 8:40 AM, Jeremy Mitchell <[email protected]> wrote: > I think this all sounds very promising. Some advantages that I see are: > > - docs never drift from API implementation (currently our docs get out of > sync real fast) > - this provides yet another interface - > https://app.swaggerhub.com/apis/dewrich/traffic-ops_api/1.3 - (in > addition > to TP) to interact with the API > - a great way to demonstrate / educate developers on the capabilities of > the api > > plus, i heard some bonus features that could be really interesting: > > - auto generation of a TO golang client. can we deprecate the old TO client > in favor of an auto-generated one? The current TO client never seems to > stay in sync with the api > - generating server stubs > > imo our api can never be fully auto-generated because of the business logic > that needs to be accounted for....but it would be pretty neat if all we had > to do was "define" the api in a yaml file and that yaml file would spit out > documentation, tests, clients (be it golang or java or whatever), and > server side code (stubs) and then all we could focus on writing code > specific to business logic. > > my guess is to really do this right, we'd have to rev the api version to > 2.0 to make the api more swagger friendly...tools (swagger) like > consistency and our api is far from consistent... > > jeremy > > On Wed, Feb 14, 2018 at 10:08 AM, Durfey, Ryan <[email protected]> > wrote: > > > I am +1 on the swagger concept. This makes working with APIs much easier > > for non-developer staff and makes it easier to educate customers as well. > > > > Ryan Durfey M | 303-524-5099 > > CDN Support (24x7): 866-405-2993 or [email protected]<mailto: > > [email protected]> > > > > From: Dewayne Richardson <[email protected]> > > Reply-To: "[email protected]" < > > [email protected]> > > Date: Wednesday, February 14, 2018 at 9:34 AM > > To: "[email protected]" < > > [email protected]> > > Subject: Traffic Ops API Swagger Doc > > > > 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<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 > > > > >
