juneau-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Blackmon <sblack...@apache.org>
Subject Re: Better Swagger UI?
Date Thu, 28 Dec 2017 16:46:28 GMT
 Hi Gary,

swagger-ui and similar tools can often bootstrap from an HTTP/HTTPS
endpoint.

So it may be possible for your endpoint(s) to expose their swagger as JSON
via OPTIONS and/or GET calls, and run the visualization layer separately.

P.S. CORS may be an issue in advanced setups.

P.P.S. I do see value in an Apache project working on libraries, micro
services, and examples for Java OpenAPI implementations. It’s an
interesting space and I’m not aware of any others that are focused on that
problem currently.

Steve

Sent from Astro <https://www.helloastro.com> for Mac

On Dec 28, 2017 at 10:35 AM, Gary Gregory <garydgregory@gmail.com> wrote:


On Wed, Dec 27, 2017 at 6:35 PM, James Bognar <jamesbognar@apache.org>
wrote:

Hi Gary,

I have actually been giving that some thoughts. I haven't looked at the
Swagger code. Since we produce Swagger 2.0 JSON, it might be easy to plug
it in and generate the page from our servlets?


I think so. For our product, the current Juneau HTML static UI for the
Swagger file is not acceptable, so I have to do something.

I am going to have to replace the Juneau HTML with the Swagger version,
either 'on the side' or as a change set that is more of an integration with
Juneau.

I am not sure when I will work on this but it will be sooner rather than
later so perhaps we can collaborate.


The approach I had been kicking around was creating our own Swagger HTML
beans to generate the same look-and-feel shown on that page. The
HtmlRender objects are open-ended and allow you to produce any
HTML/CSS/Javascript combination. So creating the same basic look and
behavior should be possible (although the dynamic "try-it-out" behavior
would be stretching it).

Approach #1 would require a new code dependency (and licensing concerns?).


No licensing issue as swagger-ui uses the Apache 2.0 license:
https://github.com/swagger-api/swagger-ui

I plan on using the Swagger code no matter what. I do not see the point in
re-inventing the wheel. Unless Juneau provides something just as good and
pretty as swagger-ui. But again, why reinvent that.

Approach #2 would be more work (probably).


The other feature enhancement I was considering was aggregated Swagger
docs. Currently, each resource/servlet has it's own Swagger doc. It
wouldn't be difficult to aggregate them by traversing the child resources
so that the entire uber-Swagger doc could be retrieved from the root
resource.

btw....I haven't forgotten about the doc request for changing the page
icon. I'm planning on including the info in a general "branding"
documentation section.


Thank you. I can figure this kind of stuff just by digging through the
code, but it would be nice to save time for others and document it.

Gary





On Wed, Dec 27, 2017 at 7:45 PM, Gary Gregory <garydgregory@gmail.com>
wrote:

Hi All,

Do you have any thoughts for or against using a better UI to
display/experiment with the generated Swagger. For example using the
Swagger code to provide
http://petstore.swagger.io/?_ga=2.16089590.1986586614.
1514399062-154601014.1509490919

Thank you,
Gary

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message