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