Decorator to include only public items

[sanscontext]

Is your feature request related to a problem? Please describe.

I'm working on an OAS file for a repo with a lot of private routes. In probably about 30% or less of these routes are actually exposed to the "public" partners, and the rest are used internally.

I got this working "well enough" by tagging all the routes with x-internal and then bundling with the remove-x-internal decorator. But then I had a (totally reasonable) request from one of the engineers to make this "fail closed", which is to say only include routes that are explicitly tagged, rather than relying on a dev knowing they need to tag new work and any imported routes with x-internal.

Describe the solution you'd like

I would love a built-in decorator that's something like include-only-x-public that would do sort of the inverse of remove-x-internal and keep ONLY the items explicitly tagged.

Describe alternatives you've considered

I did try to get this working with filter-in, but that can't filter on the absence of a tag, so having to have my devs remember to tag everything with x-public: false isn't any better than having them need to tag them as x-internal: true.

Additional context

From a WritetheDocs slack thread. :)

[tatomyr]

Hi @sanscontext, would the filter-in decorator serve your purpose? Something like the following:

    decorators:
      filter-in:
        property: operationId
        value: [createSpecialEvent, listSpecialEvents]

or

    decorators:
      filter-in:
        property: x-public
        value: true

or

    decorators:
      filter-in:
        property: x-visibility
        value: public

[tatomyr]

If that doesn't work, you can use a custom decorator like the following one:

export default () => ({
  id: 'plugin',
  decorators: {
    oas3: {
      'filter-operations': (opts) => {
        let usedOperations = [];
        let unusedOperations = [];
        let unusedPathItems = [];
        return {
          Paths: {
            enter() {
              unusedPathItems = [];
            },
            leave(paths) {
              unusedPathItems.forEach((pathItem) => {
                delete paths[pathItem];
              });
            },
            PathItem: {
              enter() {
                usedOperations = [];
                unusedOperations = [];
              },
              leave(pathItem, ctx) {
                unusedOperations.forEach((operation) => {
                  delete pathItem[operation];
                });
                if (usedOperations.length === 0) {
                  unusedPathItems.push(ctx.key);
                }
              },
              Operation: {
                leave(operation, ctx) {
                  if (opts.publicOperationIds.includes(operation.operationId)) {
                    usedOperations.push(ctx.key);
                  } else {
                    unusedOperations.push(ctx.key);
                  }
                },
              },
            },
          },
        };
      },
    },
  },
});

Config file:

plugins:
  - plugin.js
 
decorators:
  plugin/filter-operations:
    publicOperationIds:
      - 'public operation id 1'
      - 'public operation id 2'
      - ...

Let me know if it works for you.
You can find more examples of decorators in our Cookbook.

[sanscontext]

Hey @tatomyr , I wasn't able to get filter-in working, because it leaves in items that don't have the explicit tag, as I explained in the "Describe alternatives" section.

If I'm reading your code correctly, it looks like this plugin would have you explicitly specify which routes to include in the bundle, by operation_id? That actually might be a more graceful way than I'm currently doing it, if I can get it working. (Please standby, not sure I'm going to be able to get to this today - end of year crunch and all.)

[tatomyr]

@sanscontext sure, no problem. The code I'm suggesting may be adjusted to whatever syntax you'd like, it's just one of possible options. Please let me know if you need any help with the plugin.