I mentioned a week ago if we should use Swagger for documenting the API (with my example findings). Since I have seen no -1's the plan is to move forward with Swagger and only document the Golang Proxy routes (1.3), the Perl routes will still use the existing 1.2 API docs.
In terms of how we integrate with our existing doc the hope is to generate a new traffic-ops-api-1.3.rst file for the 1.3 api docs and hook into the mainline docs accordingly. Thanks, -Dew On Tue, Feb 20, 2018 at 10:50 AM, Jeremy Mitchell <mitchell...@gmail.com> wrote: > Eric, are you saying you never want to write RST anymore? me neither. yuck! > > On Tue, Feb 20, 2018 at 9:57 AM, Eric Friedrich (efriedri) < > efrie...@cisco.com> wrote: > > > Is it possible to take the swagger generated documentation and have that > > automatically included in the read-the-docs site? > > > > Asked another way: Can swagger generate docs in ReStructed Text (.rst) > > format? > > > > —Eric > > > > > > > On Feb 20, 2018, at 11:38 AM, Dave Neuman <neu...@apache.org> wrote: > > > > > > 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 < > mitchell...@gmail.com> > > > 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 < > ryan_dur...@comcast.com > > > > > >> 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 cdn_supp...@comcast.com<mailto: > > >>> cdn_supp...@comcast.com> > > >>> > > >>> From: Dewayne Richardson <dewr...@gmail.com> > > >>> Reply-To: "dev@trafficcontrol.incubator.apache.org" < > > >>> dev@trafficcontrol.incubator.apache.org> > > >>> Date: Wednesday, February 14, 2018 at 9:34 AM > > >>> To: "dev@trafficcontrol.incubator.apache.org" < > > >>> 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 > > >>> 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 > > >>> > > >>> > > >> > > > > >
