Visualize the OpenAPI document at a standard URI

[EricWittmann]

At our weekly hangout today we discussed the possibility of a spec-defined URL where a user could visualize the generated OpenAPI document. The idea is that the spec would indicate how to enable/disable such a feature and specify where a user could find such a visualization. This would probably be similar to validation in approach (config property to enable/disable and well defined endpoint to load the UI) but is also open for discussion of course.

As an example of what this might look like for a vendor - Open Liberty provides an endpoint (e.g. /openapi/ui that results in Swagger UI being opened with the generated OpenAPI document.

[arthurdm]

Circling back to this one. To make it more standard, should the URL (if available), always be /openapi/ui?

[kenfinnigan]

As something like Swagger UI is usually for development purposes, should it's existence and URL be mandated by the spec?

For instance in Quarkus we only make it available in development mode. Does that mean Quarkus wouldn't be compliant with the spec if it wasn't available outside dev mode?

[arthurdm]

I think that's very reasonable to only have it available in certain modes. But when it is available, should it always be in a standard URL? I think it should.

[kenfinnigan]

I'm ok with a default URL, but it should be configurable.

How would this play out in terms of the spec and TCK? Would it require implementations to offer a bundled Swagger UI, or would it be optional?

[arthurdm]

This would be optional.

My view is that, if a vendor does support it, it should be at /openapi/ui, just like we have /openapi (non-configurable). Easier for consumers to know where to look.

[arthurdm]

We discussed this at the hangout today and decided the right course of action is:

• make it optional for vendors to support a UI
• if they do support it, it must be at the /openapi/ui URL (the thought here is that if someone wants to configure the path to reach the UI they will most likely use Ingress / Routes or another web proxy)

@kenfinnigan and others - if you have a scenario in mind that goes against this direction please let us know.

[jmini]

just like we have /openapi (non-configurable).

I think a vendor can decide to offer an option to configure it. If users do that, they will no longer be compliant with this MP-OpenAPI spec, but it is their choice.

Quarkus has quarkus.smallrye-openapi.path to change the path.

[EricWittmann]

Well, I would say that implementors are always free to offer whatever non-conforming options they choose. So out of scope of the spec document IMO.

[arthurdm]

I agree @EricWittmann

Seeing that there have been no objections to our latest proposal I added the help wanted label so anybody can pick this up and complete it.