Add proposal SOAR-0008: OpenAPI document filtering

[simonjbeaumont]

Motivation

We'd like to run a proposal for filtering the OpenAPI document for just the required parts prior to generating.

Modifications

• Add SOAR-0008: OpenAPI document filtering

(See the proposal itself for details)¹

Result

n/a

Test Plan

n/a

Related Issues

#285

Footnotes

1. https://github.com/apple/swift-openapi-generator/pull/303/files ↩

[czechboy0]

Thanks, @simonjbeaumont!

This proposal is now In Review, which will run until October 5 - feel free to leave your feedback either on this PR or on the corresponding Swift Forums post.

[porglezomp]

Should it be possible to exclude tags as well as include them?
I'm thinking of cases like an API where some endpoints are tagged as higher privileged, and a low-privilege client might want to exclude those endpoints.

[simonjbeaumont]

Should it be possible to exclude tags as well as include them? I'm thinking of cases like an API where some endpoints are tagged as higher privileged, and a low-privilege client might want to exclude those endpoints.

Thanks for taking the time to provide feedback.

I think this is a compelling example of tag-based filtering (e.g. filtering for only readonly). However, this would only be useful in conjunction with finer-grain filtering that can filter at the operation level. Currently the smallest unit of inclusion is a path, and filtering a path for specific operations was called out in the proposal as a future direction.

I'm keen to explore if this can be delivered incrementally, on top of this proposal. Specifically, can we can confirm this additional functionality be added in a backwards-compatible way?

For filtering for operations, this seems like it would compose pretty cleanly: just add an operations key to the filter config.

For excluding, we could consider using a prefix character to negate the pattern, e.g. !, which is similar to how gitignore works. The alternative here would be to move each of the current filters into an explicit "include", e.g.

filter:
  tags:
    include:
    - "t"
    exclude:
    - "rw"

Personally, I'm not sure it's worth the additional nesting, and would prefer the negation prefix, e.g.

filter:
  tags:
    - "t"
    - "!rw"

In either event, we would need to consider the precedence between include and exclude, which is why I'd prefer for this to come in its own feature.

On that note, @porglezomp, we would certainly consider a followup proposal to this one, to add this functionality, if that's something you wanted to drive. The process for this is documented here.

[czechboy0]

I quite like the "!" prefix, and I agree this should all compose nicely, so folks are encouraged to propose further extensions of this feature.

[porglezomp]

Another possible option that doesn't add nesting but keeps out-of-band signaling would be:

filter:
  tags:
    - "t"
    - not: "rw"

Although I think ! is safe because tags are required to be valid URI characters.

[simonjbeaumont]

@porglezomp On reflection, I think that we want to include filtering at the operation level (cf. path) from the start. I have updated the proposal to bring that part forward from the "Future directions" section into the proposed changes and updated the PoC branch with an implementation.

At this time I haven't added support for excludes or complement filters.

As this feedback was incorporated pretty late in the review period, I'm proposing we extend it for a few days.

Please let me know your thoughts on the updates.

[czechboy0]

Thanks @simonjbeaumont, looks great - okay, let's extend the review period into next week.

[czechboy0]

Hi folks,

this proposal did not receive additional feedback after the extension last week, so it's now Ready for Implementation and considered Approved.

Thank you, @simonjbeaumont!

[czechboy0]

Actually wait - please add it to the Proposals.md page so that it's linkable.