Redocly / Redocly/redocly-cli

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

Open
#1,525 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

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.

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?

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.