Split only the schemas

[krishnan-techconative]

Is your feature request related to a problem? Please describe.

It would be beneficial to have a capability that allows us to isolate only the schemas from the source openApi.yaml file, leaving the paths intact

Describe the solution you'd like

Perhaps we could implement a flag or configuration option to facilitate splitting only the schemas located within the 'components' section, effectively replacing the references in the openapi.yaml file.

[lornajane]

We're unlikely to add another configuration option because it's so easy to end up with a huge and bewildering number of them, but I'm curious to hear more about your use case. Could you say something about why either splitting the API description, or maintaining a schema with an alternative manual structure, aren't working well for you?

[krishnan-techconative]

Hi @lornajane

First, let me thank you for your prompt response.

Initially, our development process involved using the OpenAPI spec without organizing it into multiple files. This approach was followed across more than 25 services. Essentially, we utilized the open-api-generator Maven plugin to generate server code and model classes. However, we've now recognized the need to separate schemas for easier maintenance. I experimented with Redocly Split, which effectively splits schemas and paths. However, upon splitting, the OpenAPI generator fails to generate server code and models correctly. It attempts to create a separate model class for one of the properties, which is incorrect. Therefore, I aim to split only the schemas, not the paths, across all services without manual intervention. In my search for a solution, I came across your tool and identified it as potentially aiding in this schema-splitting task."

[lornajane]

I think I understand. It's a common use case to split the OpenAPI descriptions to make easier maintanance, but as you have already discovered, not all tools support that structure. I suggest that you use the split structure as the source of truth, but try bundling the API description back to a single file before passing it to the code generator tools.

[lornajane]

Closing since it's unlikely that we'd implement additional options for partial splitting. My recommendation is to split the files to make them easier to work on, but if needed then run a bundle command before passing the API description to other tools.