Preserve external components in `split` output

[ctreatma]

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

[tatomyr]

As far as I see Redocly CLI split command produces a valid definition. Looks like an issue on openapi-generator's side.

[ctreatma]

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.

[tatomyr]

I see your point, thanks for the explanation.

[adamaltman]

Did you try to bundle first before passing it to the generator?