Support internalFlagProperty as a list for remove-x-internal decorator
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.
I have an API that I bundle for 2 different usages:
- publishing to GitHub
- publishing to our documentation platform
We have 2 use cases that involve hiding functionality:
- Our documentation platform has the ability to hide pages so they can only be accessed via a direct link. Sometimes we want to publish endpoints that are private in this way and NOT included when we bundle the spec for GitHub.
- Beta/internal-only features that should not be included when we bundle the spec for either our documentation platform or GitHub
The relevant part of our redocly.yaml configuration:
apis:
external-readme:
root: openapi/openapi.yaml
decorators:
remove-x-internal:
internalFlagProperty: 'x-remove-from-readme'
external-github:
root: openapi/openapi.yaml
decorators:
remove-x-internal:
internalFlagProperty: 'x-remove-from-github'
Right now, if we want to accomplish the second use case, we have to include BOTH x-remove-from-readme and x-remove-from-github on the relevant node. I introduced this behavior yesterday and I already ran into an issue where we forgot to add one of them 😅
Describe the solution you'd like
I'd like to be able to do something like:
# redocly.yaml
apis:
external-readme:
root: openapi/openapi.yaml
decorators:
remove-x-internal:
internalFlagProperty:
- 'x-internal'
external-github:
root: openapi/openapi.yaml
decorators:
remove-x-internal:
internalFlagProperty:
- 'x-remove-from-github'
- 'x-internal'
So that I can accomplish use case 1 by using x-remove-from-github and use case 2 by only using x-internal. In this case, I would expect nodes with x-internal to be removed from both bundled versions of the spec.
Describe alternatives you've considered
Mostly just the current behavior I'm using described above. I've also considered using filter-out to handle use case 1 and filter out specific APIs based on tag or something, but I don't like it. I'd like for it to be obvious which endpoints are filtered out within the definition for those specific endpoints. Also I have some endpoints that use the same tag but only some of them need to be hidden from the GitHub bundled version. I could use summary or something, but what if it gets changed?
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 by reviewing the remove-x-internal decorator configuration described in redocly.yaml and how internalFlagProperty is interpreted. Add coverage for both a single flag and a list of flags, verifying that nodes matching any configured property are removed from the corresponding bundled OpenAPI output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100