date:20180220

Re: Traffic Ops API Swagger Doc

2018-02-20 Thread Jeremy Mitchell

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  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 
> > 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 forbut 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  >
> >> 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 DurfeyM | 303-524-5099
> >>> CDN Support (24x7): 866-405-2993 or cdn_supp...@comcast.com >>> cdn_supp...@comcast.com>
> >>>
> >>> From: Dewayne Richardson 
> >>> 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
> >>> 
> 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
> >>>  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

Re: Traffic Ops API Swagger Doc

2018-02-20 Thread Dewayne Richardson

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 
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  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 > >
>> > 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 forbut 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 DurfeyM | 303-524-5099
>> >>> CDN Support (24x7): 866-405-2993 or cdn_supp...@comcast.com> >>> cdn_supp...@comcast.com>
>> >>>
>> >>> From: Dewayne Richardson 
>> >>> 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
>> >>> 
>> 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
>> >>>

Re: Traffic Ops API Swagger Doc

2018-02-20 Thread Dewayne Richardson

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  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 
> > 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 forbut 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  >
> >> 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 DurfeyM | 303-524-5099
> >>> CDN Support (24x7): 866-405-2993 or cdn_supp...@comcast.com >>> cdn_supp...@comcast.com>
> >>>
> >>> From: Dewayne Richardson 
> >>> 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
> >>> 
> 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
> >>>  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)
> >>>

Re: Traffic Ops API Swagger Doc

2018-02-20 Thread Eric Friedrich (efriedri)

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  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 
> 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 forbut 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 
>> 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 DurfeyM | 303-524-5099
>>> CDN Support (24x7): 866-405-2993 or cdn_supp...@comcast.com>> cdn_supp...@comcast.com>
>>> 
>>> From: Dewayne Richardson 
>>> 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
>>>  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
>>>  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
>>> >> trafficcontrol/blob/swagger-demo/traffic_ops/traffic_ops_
>>> golang/docs/swagger.json>> dewrich/incubator-trafficcontrol/blob/swagger-

Re: Traffic Ops API Swagger Doc

2018-02-20 Thread Dave Neuman

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 
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 forbut 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 
> 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 DurfeyM | 303-524-5099
> > CDN Support (24x7): 866-405-2993 or cdn_supp...@comcast.com > cdn_supp...@comcast.com>
> >
> > From: Dewayne Richardson 
> > 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
> >  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
> >  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
> >  > trafficcontrol/blob/swagger-demo/traffic_ops/traffic_ops_
> > golang/docs/swagger.json > 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

Re: Traffic Ops API Swagger Doc

2018-02-20 Thread Jeremy Mitchell

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 forbut 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 
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 DurfeyM | 303-524-5099
> CDN Support (24x7): 866-405-2993 or cdn_supp...@comcast.com cdn_supp...@comcast.com>
>
> From: Dewayne Richardson 
> 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
>  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
>  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
>  trafficcontrol/blob/swagger-demo/traffic_ops/traffic_ops_
> golang/docs/swagger.json 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
>
>

Re: Traffic Ops API Swagger Doc

Re: Traffic Ops API Swagger Doc

Re: Traffic Ops API Swagger Doc

Re: Traffic Ops API Swagger Doc

Re: Traffic Ops API Swagger Doc

Re: Traffic Ops API Swagger Doc

6 matches

Site Navigation

Mail list logo

Footer information