redocly-cli
redocly-cli copied to clipboard
Support internalFlagProperty as a list for remove-x-internal decorator
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?