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 

From: Dewayne Richardson <dewr...@gmail.com>
Reply-To: "dev@trafficcontrol.incubator.apache.org" 
Date: Wednesday, February 14, 2018 at 9:34 AM
To: "dev@trafficcontrol.incubator.apache.org" 
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

*Sample TO API doc *


*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)

And the *asns.go*, *cdns.go*, *divisions.go*, *regions.go* and *statuses.go*
structs in my branch here:

*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


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.


Reply via email to