Update mpOpenApi reference pages to include the endpoints which the feature creates

[Azquelt]

The mpOpenAPI-x.x features all create these endpoints:

• /openapi - returns the OpenAPI document in yaml or json format
  • the Accept header can be used to select yaml or json (required in spec)
  • alternatively, the URL parameter format=yaml/json can be added to select json or yaml (recommended in spec)
• /openapi/ui - displays the OpenAPI information as an interactive web page (not part of spec)

[dmuelle]

Hi @Azquelt - can you provide (or recommend someone who can) code examples that demonstrate these endpoints? We generally just include configuration examples on the feature reference pages. Though I'm not sure that any explicit configuration beyond enabling the feature is needed here, examples similar to what we have for mp Health, which show the client code and API response, might be helpful.

[Azquelt]

There's no code example to for the endpoint. The point of the mpOpenApi feature is to create an OpenAPI document which is served from an endpoint. We just need to document where that endpoint is.

We also provide a UI for browsing the OpenAPI document on a different endpoint and we need to document that too.

[Azquelt]

There's a much larger piece of work to document fully how to use the mpOpenApi feature in #340, but I'm not sure when that will be ready.

However, the information about what endpoints the feature provides is basic and minimal and should be added sooner.

[dmuelle]

Ok thanks- we are targeting the info in #340 to publish in 21.0.0.2, so it should be able to publish in the same release that documents these endpoints.

In general, the non-autogenerated content on the feature pages consists of examples. Since there are no relevant code/configuration examples for this feature, would it be helpful to provide example endpoint URLs or annotations (however the endpoints are used) and the API documents that they would generate, along with the explanation of the endpoint? We might also document the endpoints in #340 and point to that doc from this page.

[chirp1]

Epic for the issue: OpenLiberty/open-liberty#11020

[Azquelt]

While it would be good to have a full example and demonstration of how to use the mpOpenAPI feature (as I think will be covered by #340), I raised this issue to just add the basic information of where the endpoint is. This is crucial, basic reference information, which I could currently only find documented in the middle of the guide.

I would suggest adding something like this:

When the feature is enabled and an application which includes JAX-RS resources is deployed, the created Open API document is made available over HTTP or HTTPS at the /openapi enpoint.

In addition, a user interface for browsing the Open API document is made available at the /openapi/ui endpoint.

For example, when starting a local development server with the default ports, the Open API document would be available at http://localhost:9080/openapi and the user interface would be available at http://localhost:9080/openapi/ui.

If you don't think that information is worth including without the context of a fuller example, then you can close this issue and ensure that it's documented as part of #340.

[msmiths]

The existing documentation does include the /openapi endpoint... but it is hidden away on this page:

https://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_mpopenapi.html

See Step 6 in the Procedure section.

[Rwalls1]

These updates will be completed with issue #340.