Support internalFlagProperty as a list for remove-x-internal decorator

[samanthawritescode]

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:

1. 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.
2. 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?

[lornajane]

Thanks @samanthawritescode ! I think this aligns pretty closely with existing issue #970, where you could at least add the decorator multiple times for the API description that wants two sets of filtering applied.

I think your current options are either the filter-out decorator as you already mentioned, to use a custom plugin that does something similar and accepts multiple things-to-remove, or to prepare the the documentation version of the OpenAPI file by applying filtering to the result of preparing the GitHub version (hopefully that makes sense).

[samanthawritescode]

Thanks @lornajane for the response! I agree that existing issue is related. I didn't even think to try something like that.

Preparing the documentation version of the spec by applying filtering to the result of the GitHub version is interesting, I'll consider it. Clever idea.