new decorators: `filter-in` and `filter-out`

Is your feature request related to a problem? Please describe. Users need to generate different “slices” of single OpenAPI definition for different audiences.

For example, “include only API endpoints with x-audience set to public”.

This is more advanced version of remove-x-internal which covers only basic use case.

Describe the solution you’d like We need two decorators filter-in and filter-out.

filter-in

Keep nodes that have specific property set to the specific value. Arrays should be supported too. If the property is not set on the node it should be kept too.

filter-in:
  property: x-audience
  value: [Public, Partner] 

In the example above value should support arrays. If x-audience in the definition is an array too the node should be kept if only two arrays have at least one element in common. We can implement matchStrategy option to alter this behavior with values: ‘any’ or ‘all’.

filter-out

It’s same as filter-in but it removes nodes that have specific property set to the specific value.

filter-out:
  property: x-audience
  value: Private 

Describe alternatives you’ve considered filter-out-permission and filter-in-permission

Additional context Add any other context or screenshots about the feature request here.

[adamaltman]

I think all is more clear than every. It could be just all and any.

[RomanHotsiy]

Another interesting use-case: splitting single source of truth definition into smaller chunks by tags:

apis:
  users@v1:
    root: ./big-oas.yaml
    lint:
      decorators:
        filter-in:
          property: tags
          value: [Users, Account] 
  payments@v1:
    root: ./big-oas.yaml # same root
    lint:
      decorators:
        filter-in:
          property: tags
          value: [Payments, CreditCards, Transactions]