Eric: Out of curiosity I was able to generate it with the tooling I mentioned here:
https://github.com/dewrich/incubator-trafficcontrol/blob/swagger-demo/traffic_ops/traffic_ops_golang/docs/swagger.rst -Dew On Tue, Feb 20, 2018 at 10:38 AM, Dewayne Richardson <dewr...@gmail.com> wrote: > 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 >> >>> >> >>> >> >> >> >> >
