Project specific OpenAPI with custom rest controllers

Support
1

Dear support,

a Jmix application provides some Rest endpoints with custom business logic. I want to provide an OpenAPI documentation in an automated way.

Defining the endpoint as mentioned in the documentation
https://docs.jmix.io/jmix/2.7/rest/api-docs.html#project-specific-open-api-documentation
provides the generic endpoints and would also consider endpoints by rest services but does not for springboot rest controller endpoints.

Is there a way to merge them?

2

Hi,

No, Jmix does not currently merge OpenAPI documentation for Jmix REST endpoints and arbitrary Spring MVC @RestController endpoints.

The documentation available under /rest/docs/openapiDetailed.json is generated by the Jmix REST add-on and covers the Generic REST API: entities, queries, and REST services exposed via @RestService / @RestMethod. Regular Spring controllers are not processed by this generator.

For custom Spring MVC controllers, you can use springdoc-openapi. It will generate a separate OpenAPI document, usually at /v3/api-docs.

The usual way to combine them from the user’s point of view is to configure Swagger UI with two OpenAPI URLs:

springdoc.paths-to-match=/api/**

springdoc.swagger-ui.disable-swagger-default-url=true

springdoc.swagger-ui.urls[0].name=Jmix REST API
springdoc.swagger-ui.urls[0].url=/rest/docs/openapiDetailed.json

springdoc.swagger-ui.urls[1].name=Custom API
springdoc.swagger-ui.urls[1].url=/v3/api-docs

This gives one Swagger UI page with a selector for both APIs.

If you need a single OpenAPI JSON file, then you would need to implement a custom merge step yourself. But in most cases, keeping two specs and exposing them through the same Swagger UI is simpler and more maintainable.

Regards,
Dmitry

1 Like