Yes the plan was to get the initial thumbs up, then figure out how we can deploy it (by default swagger generates interactive, meaning it needs a server, UI doc). A quick internet search says there does look like tooling for converting swagger docs to .rst ( https://github.com/Arello-Mobile/swagger2rst).
Once we see that it's going to all work out then we'll start removing the old API docs and hook in the new ones. -Dew 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 > >>> > >>> > >> > >
