Quarkus: Document how to publish custom OpenAPI design document (instead of driven by the code)

[hantsy]

Currently the OpenAPI generate schema from JAX-RS codes. This is code first way.

But some API description is not clear enough, we have to use the Microprofile OpenAPI annotations to enrich it. Thus a lots of codes in Jax-rs are MP OpenAPI annotations.

In my experience, some projects require Design APIs firstly. There are some tools can do this, such as Swagger Editor. We can a well defined schema there.

Is it possible let OpenAPI load a predefined schema file(such as specify the file in classpath in the application.properties ) instead of generating from the JAX-RS codes?

[machi1990]

Related to https://github.com/quarkusio/quarkus/issues/3905

[stuartwdouglas]

This should already exist. It should be able to read from:

private static final String META_INF_OPENAPI_YAML = "META-INF/openapi.yaml";

private static final String WEB_INF_CLASSES_META_INF_OPENAPI_YAML = "WEB-INF/classes/META-INF/openapi.yaml";

private static final String META_INF_OPENAPI_YML = "META-INF/openapi.yml";

private static final String WEB_INF_CLASSES_META_INF_OPENAPI_YML = "WEB-INF/classes/META-INF/openapi.yml";

private static final String META_INF_OPENAPI_JSON = "META-INF/openapi.json";

private static final String WEB_INF_CLASSES_META_INF_OPENAPI_JSON = "WEB-INF/classes/META-INF/openapi.json";

[machi1990]

I mis-read the issue and I thought it was asking generated JAX-RS from OpenApi definition.
After re-reading it again, indeed OpenAPI schema can be loaded from a pre-defined schema as indicated by Stuart above. In such a workflow it is interesting to also disable annotation scanning with mp.openapi.scan.disable=true

[emmanuelbernard]

Re-qualifying as a documentation issue. @machi1990 if you have a few mins, you can take stuart's message to update our openapi guide

[hantsy]

@machi1990 Hm, can we implement it like: If there is a openapi.json/yml existed, then the "Scan" is disabled by default.
And the openapi schema file name(eg. myapi.json etc) may be customized via configuration.

[machi1990]

@machi1990 Hm, can we implement it like: If there is a openapi.json/yml existed, then the "Scan" is disabled by default.
And the openapi schema file name(eg. myapi.json etc) may be customized via configuration.

Interesting, @emmanuelbernard asked for the same thing here https://github.com/quarkusio/quarkus/pull/3932#discussion_r322200834 and opened a question in our mailing https://groups.google.com/forum/#!msg/quarkus-dev/HOLYbfWr4T8/khdNGlSnAwAJ

Either way, I think this should be an issue apart.