Re: [DISCUSS] - Integrating Knox with Swagger

[Sandor Molnar <sm...@cloudera.com.INVALID>]

Hi folks,

I've created the JIRA and submitted my first PR with the basics of Swagger
UI for Admin and Metadata API.

https://issues.apache.org/jira/browse/KNOX-2509

Sandor

On Fri, Nov 15, 2019 at 4:30 PM Kevin Risden <kr...@apache.org> wrote:

> I am definitely a fan of avoiding the disconnect we have between
> documentation and code. The Admin API would be a great place to clean that
> up and Swagger seems like a reasonable tool to do so.
>
> Kevin Risden
>
>
> On Wed, Nov 13, 2019 at 9:59 PM Sandeep Moré <mo...@gmail.com>
> wrote:
>
> > Agreed +1 !
> >
> > On Wed, Nov 13, 2019 at 4:05 PM larry mccay <la...@gmail.com>
> wrote:
> >
> >> + dev@...
> >>
> >> Thank you for the idea!
> >>
> >> Yes, I am familiar with Swagger and that would be huge for our current
> >> APIs and others that may come along.
> >> I think the effort to add a swagger filter or the like will be only one
> >> part of the larger effort of how it integrates into Knox, the site, the
> >> Admin UI, the docs, etc.
> >>
> >> I think that a KIP detailing the full vision would make a lot of sense.
> >>
> >> +1 on moving forward with a KIP and/or JIRA to continue discussion and
> >> tease out design considerations.
> >>
> >> On Wed, Nov 13, 2019 at 3:45 PM Sandor Molnar <sm...@cloudera.com>
> >> wrote:
> >>
> >>> Hi folks,
> >>>
> >>> recently I had some contribution that allows end-users managing service
> >>> definitions without restarting the Knox Gateway. See
> >>> https://issues.apache.org/jira/browse/KNOX-2053 and
> >>> https://issues.apache.org/jira/browse/KNOX-2056 for further details.
> >>>
> >>> I've been just about creating a new JIRA to document those new API
> >>> endpoints in Knox user guide but it has come to my mind that we can do
> it
> >>> much better by using Swagger.
> >>>
> >>> Given the fact, the Admin API does not consist of hundreds of existing
> >>> endpoints it should not be 'that' huge work. I personally believe the
> >>> project would gain a lot by using this very useful tool (e.g. Admin API
> >>> documentation would be generated out-of-the-box, no more documentation
> >>> JIRAs required. Moreover, the generated documentation would be in sync
> with
> >>> the actual implementation).
> >>> You can check this out here: https://swagger.io/tools/swagger-ui/
> (there
> >>> is a live demo too; it's worth looking at).
> >>>
> >>> Any comments, ideas are welcome!
> >>>
> >>> Cheers,
> >>> Sandor
> >>>
> >>
>