Implement support for multiple openapi documents #51760

Postremus · 2025-12-30T18:21:45Z

Implement support for multiple openapi documents.

...yment/src/main/java/io/quarkus/smallrye/openapi/common/deployment/SmallRyeOpenApiConfig.java

Postremus · 2025-12-30T18:29:37Z

...eployment/src/main/java/io/quarkus/smallrye/openapi/deployment/SmallRyeOpenApiProcessor.java


-        routes.produce(RouteBuildItem.newManagementRoute(openApiConfig.path(), MANAGEMENT_ENABLED)
-                .withRouteCustomizer(corsFilter)
-                .withRoutePathConfigKey("quarkus.smallrye-openapi.path")


I did not understand what withRoutePathConfigKey is used for?
Since the path is already passed through the newManagementRoute anyway.
Is this used for runtime config path selection? That would not be needed here since this config is buildtime only.

I dunno. Maybe @MikeEdgar would know?

Would it be possible to keep it the way it is?

Yes. Would require me to manually build the config keys in this case.

But - I would still like to know what this does. :)

Apperantly, right now this does nothing anymore.

Was the only use. withRoutePathConfigKey gets mapped to ConfiguredPathInfo in io.quarkus.vertx.http.deployment.RouteBuildItem#getRouteConfigInfo

But getConfiguredPathInfo is unused.

Only user was the Devconsoleprocessor from old devui:

19aae16c113#diff-5d886c297bbf81799a7e65ae5aec5de0966e6a5dbe06641a569a7c5afa0cf5b1

No other users in quarkiverse / camel-quarkus.

I can add it back for now, and someone else does a complete cleanup of the associated build items later on?

Postremus · 2025-12-30T18:32:32Z

...i/spi/src/main/java/io/quarkus/smallrye/openapi/deployment/spi/OpenApiDocumentBuildItem.java

 * The final OpenAPI Document as generated by the Extension.
 */
-public final class OpenApiDocumentBuildItem extends SimpleBuildItem {
+public final class OpenApiDocumentBuildItem extends MultiBuildItem {


Since OpenApiDocumentBuildItem is part of an spi module, I guess it could also be consumed by other extensions?

Is it safe to change a build item from SimpleBuildItem to MultiBuildItem, or do the buildsteps that rely on this builditem just break?

I guess the buildsteps will break, since a SimpleBuildItem is usually injected without a Collection wrapper.. Might need to add a new builditem..

I reverted the changes from OpenApiDocumentBuildItem and created a new MultiBuildItem OpenApiNamedDocumentBuildItem, where one is created for each generated document.

However, @phillip-kruger is the OpenApiDocumentBuildItem even used anywhere? Not found any uses in quarkus.
You know of any extensions?

quarkus/extensions/smallrye-openapi/deployment/src/main/java/io/quarkus/smallrye/openapi/deployment/SmallRyeOpenApiProcessor.java

Lines 1021 to 1029 in 6ef44db

* We need to use the deprecated OpenApiDocument as long as

* OpenApiDocumentBuildItem needs to be produced.

*/

@SuppressWarnings("deprecation")

OpenApiDocument toOpenApiDocument(SmallRyeOpenAPI finalOpenAPI) {

OpenApiDocument output = OpenApiDocument.newInstance();

output.set(finalOpenAPI.model());

return output;

}

Makes me think that the builditem is not that useful anymore. Maybe deprecate it, and not provide an alternative?

So usually, what I do in this case is look for usage in the Quarkiverse org and Camel Quarkus project.

You can see that the build item is used in the Backstage extension here: https://github.com/search?q=org%3Aquarkiverse+OpenApiDocumentBuildItem&type=code . This will break as we need to make it a list.

Now, we can adjust the project in a way that is backward compatible by just making it a list and it should work with other versions so I think I would favor this approach rather than introducing the new build item whose name looks a bit artificial.

Now I don't know if your changes to OpenApiDocumentBuildItem would break Backstage? I suppose you had maybe a isDefault() method? You won't be able to call it always but maybe we could have something that only calls it if there are multiple documents? That way, I think it would somehow work?

Yeah I believe that could work.

We will only call .isDefault() when there is already a multipleOpenApiDocumentBuildItem given, which can only happen on 3.31.

All other documents than the default document will be ignored for a start. Support for multiple openapi documents can then be added later

I will prepare a PR for backstage. Lets hope they accept this idea. :)

Done.

OpenApiDocumentBuildItem is now a MultiBuildItem.

backstage PR.

quarkiverse/quarkus-backstage#136

Okay, so backwards compatibility won't work (at least this way). Quarkus does not want to injects a SimpleBuildItem as a List.
https://github.com/quarkiverse/quarkus-backstage/pull/136/checks

...e-openapi/runtime/src/main/java/io/quarkus/smallrye/openapi/runtime/OpenApiConfigHelper.java

Postremus · 2025-12-30T18:47:06Z

The changes themselve work, i.e. I now have multiple openapi documents in my application.

For now this pull request is a draft.
I still have a few questions, see my comments on the code.

github-actions · 2025-12-30T18:59:06Z

🎊 PR Preview b4e83ad has been successfully built and deployed to https://quarkus-pr-main-51760-preview.surge.sh/version/main/guides/

Images of blog posts older than 3 months are not available.
Newsletters older than 3 months are not available.

gsmet · 2026-01-01T13:56:07Z

Interesting work. Let’s have a proper discussion with the maintainer of SmallRye OpenApi when we’re all back.

gsmet

Thanks a lot for this work! I added a few comments here and there, mostly cosmetic.

docs/src/main/asciidoc/openapi-swaggerui.adoc

gsmet · 2026-01-06T09:07:32Z

...yment/src/main/java/io/quarkus/smallrye/openapi/common/deployment/SmallRyeOpenApiConfig.java

+
+    String DEFAULT_DOCUMENT_NAME = "<default>";
+
+    String DEFAULT_PATH = "openapi";


I wonder if you should also use a <default> value here and resolve it later given it's not exactly always the default value?

We could maybe use:

@ConfigDocDefault(""" Either * openapi for the default document * Or openapi-<document-name> for any named document

On OpenApiDocumentConfig path / storeSchemaDirectory.

That would make it extra clear for users how this value is determined - in addition to the description.

Alternatively, something like openapi-<document-name> as sole default value? But my fear is that users then expect the <document-name> pattern to work in other places of the openapi config.

...yment/src/main/java/io/quarkus/smallrye/openapi/common/deployment/SmallRyeOpenApiConfig.java

gsmet · 2026-01-06T09:11:28Z

...eployment/src/main/java/io/quarkus/smallrye/openapi/deployment/SmallRyeOpenApiProcessor.java


-        routes.produce(RouteBuildItem.newManagementRoute(openApiConfig.path(), MANAGEMENT_ENABLED)
-                .withRouteCustomizer(corsFilter)
-                .withRoutePathConfigKey("quarkus.smallrye-openapi.path")


I dunno. Maybe @MikeEdgar would know?

Would it be possible to keep it the way it is?

gsmet · 2026-01-06T09:22:25Z

...i/spi/src/main/java/io/quarkus/smallrye/openapi/deployment/spi/OpenApiDocumentBuildItem.java

 * The final OpenAPI Document as generated by the Extension.
 */
-public final class OpenApiDocumentBuildItem extends SimpleBuildItem {
+public final class OpenApiDocumentBuildItem extends MultiBuildItem {


So usually, what I do in this case is look for usage in the Quarkiverse org and Camel Quarkus project.

You can see that the build item is used in the Backstage extension here: https://github.com/search?q=org%3Aquarkiverse+OpenApiDocumentBuildItem&type=code . This will break as we need to make it a list.

Now, we can adjust the project in a way that is backward compatible by just making it a list and it should work with other versions so I think I would favor this approach rather than introducing the new build item whose name looks a bit artificial.

Now I don't know if your changes to OpenApiDocumentBuildItem would break Backstage? I suppose you had maybe a isDefault() method? You won't be able to call it always but maybe we could have something that only calls it if there are multiple documents? That way, I think it would somehow work?

quarkus-bot · 2026-01-06T20:21:32Z

Status for workflow `Quarkus Documentation CI`

This is the status report for running Quarkus Documentation CI on commit a134781.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

Warning

There are other workflow runs running, you probably need to wait for their status before merging.

quarkus-bot · 2026-01-06T21:36:04Z

Status for workflow `Quarkus CI`

This is the status report for running Quarkus CI on commit a134781.

Failing Jobs

Status	Name	Step	Failures	Logs	Raw logs	Build scan
❌	Native Tests - Windows support	`Setup GraalVM`	⚠️ Check →	Logs	Raw logs	🚧

You can consult the Develocity build scans.

quarkus-bot bot added area/documentation area/openapi area/smallrye area/swagger-ui labels Dec 30, 2025

Postremus commented Dec 30, 2025

View reviewed changes

...yment/src/main/java/io/quarkus/smallrye/openapi/common/deployment/SmallRyeOpenApiConfig.java Show resolved Hide resolved

Postremus commented Dec 30, 2025

View reviewed changes

...e-openapi/runtime/src/main/java/io/quarkus/smallrye/openapi/runtime/OpenApiConfigHelper.java Show resolved Hide resolved

Postremus force-pushed the issues/22355-multi-open branch from c2ddb40 to 86fb0c7 Compare December 31, 2025 17:41

Postremus force-pushed the issues/22355-multi-open branch 2 times, most recently from e5a0c58 to ff049e6 Compare January 5, 2026 18:08

Postremus marked this pull request as ready for review January 5, 2026 18:13

This comment has been minimized.

Sign in to view

Postremus requested a review from phillip-kruger January 5, 2026 18:14

This comment has been minimized.

Sign in to view

gsmet reviewed Jan 6, 2026

View reviewed changes

Postremus force-pushed the issues/22355-multi-open branch from ff049e6 to 8dc15de Compare January 6, 2026 18:31

This comment has been minimized.

Sign in to view

Implement support for generating multiple openapi documents

a134781

Postremus force-pushed the issues/22355-multi-open branch from 8dc15de to a134781 Compare January 6, 2026 19:52

Postremus mentioned this pull request Jan 6, 2026

Handle multiple openapi documents gracefully quarkiverse/quarkus-backstage#136

Draft

	* We need to use the deprecated OpenApiDocument as long as
	* OpenApiDocumentBuildItem needs to be produced.
	*/
	@SuppressWarnings("deprecation")
	OpenApiDocument toOpenApiDocument(SmallRyeOpenAPI finalOpenAPI) {
	OpenApiDocument output = OpenApiDocument.newInstance();
	output.set(finalOpenAPI.model());
	return output;
	}


		String DEFAULT_DOCUMENT_NAME = "<default>";

		String DEFAULT_PATH = "openapi";

Implement support for multiple openapi documents #51760

Are you sure you want to change the base?

Implement support for multiple openapi documents #51760

Uh oh!

Conversation

Postremus commented Dec 30, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Postremus Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Postremus commented Dec 30, 2025

Uh oh!

github-actions bot commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gsmet commented Jan 1, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

gsmet left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Postremus Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

quarkus-bot bot commented Jan 6, 2026

Status for workflow Quarkus Documentation CI

Uh oh!

quarkus-bot bot commented Jan 6, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Status for workflow Quarkus CI

Failing Jobs

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Postremus Dec 31, 2025 •

edited

Loading

github-actions bot commented Dec 30, 2025 •

edited

Loading

Postremus Jan 6, 2026 •

edited

Loading

Status for workflow `Quarkus Documentation CI`

quarkus-bot bot commented Jan 6, 2026 •

edited by github-actions bot

Loading

Status for workflow `Quarkus CI`