Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add OpenAPI U/I integration [3.x] #5568

Merged
merged 21 commits into from
Dec 3, 2022

Conversation

tjquinno
Copy link
Member

@tjquinno tjquinno commented Nov 30, 2022

Resolves #4883

SmallRye offers a mostly-static content solution for presenting essentially the Swagger U/I.

This PR creates a new integration--helidon-integrations-openapi-ui--which layers on the SmallRye code, customizing the main page dynamically with some Helidon-specific content (logo, title, links) and serving the U/I at at /openapi/ui (by default) and, using content negotiation, also at /openapi.

SE developers add a build-time dependency and then create an OpenApiUi.Builder instance and add it to the OpenAPISupport.Builder if they want to customize the U/I behavior. Or, they can just let OpenAPISupport.Builder automatically create a U/I using default settings. They can use config for a few settings as well.

MP developers add a runtime dependency and use config as needed to tailor the behavior.

Changes to helidon-openapi

  • Defines some new U/I-related interfaces (OpenApiUiFactory and OpenApiUi) and contains no-op implementations.
  • OpenAPISupport:
    • Uses service loading to obtain the correct factory and get the correct OpenApiUi.Builder impl
    • Invokes the OpenApiUi update method so it can add its own routing. (none for the no-op impl) The developer's code does not explicitly register the U/I service.
    • delegates to the OpenApiUi instance upon receiving a request at /openapi so it can handle requests for text/* content.
  • Some new tests

New helidon-integrations-openapi-ui

  • Provides its OpenApiUiFactory impl and contains a full-featured OpenApiUi impl which:
    • Redirects HTML requests to /openapi and /openapi/ui to return a dynamically-computed index.html (from SmallRye) which contains JavaScript which retrieves the OpenAPI document and then runs the browser U/I)
    • Adds routing for static content, some from Helidon, some from SmallRye, used by the U/I.
  • Some Helidon-specific static content for the U/I page.
  • Tests

MP QuickStart examples

  • Added an MP OpenAPI annotation to add some information so the U/I is nicer if someone were to add the Helidon OpenAPI U/I dependency to the MP QuickStart pom manually.

Docs

  • Extensive additions to describe adding the U/I dependency and using the builder or config to tailor the behavior.
  • Removed se/openapi.adoc which was moved to se/openapi/openapi.adoc in a previous PR but I accidentally left the old file in place.
  • Fixed an unrelated typo in the OpenAPI generator doc.

@tjquinno tjquinno added this to the 3.0.3 milestone Nov 30, 2022
@tjquinno tjquinno self-assigned this Nov 30, 2022
@oracle-contributor-agreement oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Nov 30, 2022
@tjquinno tjquinno marked this pull request as draft November 30, 2022 21:33
@tjquinno tjquinno marked this pull request as ready for review November 30, 2022 22:40
Copy link
Contributor

@ljamen ljamen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't call them out individually, but perhaps we should stick to UI (vs U/I) throughout the docs? Is there a way to find/replace? The only other issue I had was with the logo.svg file. It wasn't displaying for me -- or at least it didn't look like it was?

docs/config/io_helidon_openapi_OpenApiUi.adoc Show resolved Hide resolved
docs/config/io_helidon_openapi_OpenApiUi.adoc Show resolved Hide resolved
docs/includes/openapi/openapi-ui.adoc Outdated Show resolved Hide resolved
docs/includes/openapi/openapi-ui.adoc Outdated Show resolved Hide resolved
docs/se/openapi/openapi-ui.adoc Outdated Show resolved Hide resolved
@tjquinno tjquinno merged commit f8e9149 into helidon-io:helidon-3.x Dec 3, 2022
@tjquinno tjquinno deleted the openapi-ui-one-service-3.x branch December 3, 2022 12:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
OCA Verified All contributors have signed the Oracle Contributor Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create simple wrapper around SmallRye OpenAPI U/I
3 participants