Preserve external components in `split` output
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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