Redocly / Redocly/redocly-cli

Preserve external components in `split` output

Open
#1,006 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

p3 split Type: Enhancement
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the redocly split command and its handling of bundled OpenAPI components; trace how components.schemas and other component sections are emitted after bundle-and-split. Define the flag's default and enabled behavior from the examples, then verify that external component references remain in the root openapi.yaml and that the resulting split spec works with openapi-generator.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.