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é <[email protected]> wrote: > Agreed +1 ! > > On Wed, Nov 13, 2019 at 4:05 PM larry mccay <[email protected]> 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 <[email protected]> >> 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 >>> >>
