redocly-cli
redocly-cli copied to clipboard
Preserve external components in `split` output
Is your feature request related to a problem? Please describe.
We use openapi-generator
to generate client libraries from our spec and have run into a problem generating code from a spec that has been split with redocly split
.
We maintain a split API definition, which we then bundle with redocly bundle
. We use remove-x-internal
, etc., to generate different bundled specs from the same source. We would like to then split the bundled specs so that we can provide both a bundled and a split spec. When we run redocly split
, however, we end up with a root openapi.yaml
file that has no external references under the components
key. For example:
Original root yaml file:
components:
schemas:
MyObject:
$ref: 'components/schemas/MyObject.yaml'
securitySchemes:
authToken:
description: |
HTTP header containing an authentication token
in: header
name: Authorization
type: apiKey
x-displayName: Auth Token
Root yaml file after bundle & split:
components:
securitySchemes:
authToken:
description: |
HTTP header containing an authentication token
in: header
name: Authorization
type: apiKey
x-displayName: Auth Token
When we generate code using openapi-generator
from the spec produced by redocly split
, we get errors because openapi-generator
doesn't know what name to use for the external refs.
Describe the solution you'd like
It would be nice to have a --preserve-external-component-refs
flag on the redocly split
command; by default, the split command would continue to work as it does today, but if it is run with --preserve-external-component-refs true
, the split command would produce a root openapi.yaml
file that includes external references in components.schemas
, etc.
Describe alternatives you've considered
Additional context
As far as I see Redocly CLI split command produces a valid definition. Looks like an issue on openapi-generator's side.
Both schema definitions are valid, but the one currently produced by Redocly CLI removes important information from the spec. I see nothing in the OpenAPI spec or in the JSON ref spec that specifies a mapping from the content of a $ref
(e.g., a filename) to the name of a schema object. As far as I can tell, that is a decision that exists entirely in the Redocly CLI ecosystem.
Assuming that is an accurate summary of the specs: a code generator that generates code from an OpenAPI spec can reasonably decide not to assume a mapping from the $ref
content to the referenced object's name, and to rely on the components.schema
property to include named schema objects. Both the openapi-generator-cli
and swagger-codegen
choose to generate a name for $ref
objects based on where the $ref
appears, rather than based on the value of the $ref
property. I'm hesitant to stop using those code generators, since they appear to be the most-official ones out there, but if there is a different code generator that you recommend that uses the same $ref => object name
assumption as Redocly CLI, we are happy to try it out.
I see your point, thanks for the explanation.
Did you try to bundle
first before passing it to the generator?