bump overlay: filtering by endpoints' tags

[jamietanna]

As discussed on the APIs You Won't Hate Slack, I've recently been trying to get an Overlay working to do endpoint-level filtering, based on the tags of the given endpoint

(Related: atamano/jsonpathly#12)

Spec:

openapi: 3.1.0
info:
  title: "..."
  description: "..."
  version: 1.0.0

tags:
  - name: Enterprise-Only
    description: |
      ...

paths:
  /metrics:
    get:
      operationId: getPrometheusMetrics
      responses:
        '200':
          description: "..."
          content:
            text/plain:
              schema:
                type: string
  /super/secret:
    get:
      tags:
        - Enterprise-Only
      responses:
        '200':
          description: "..."
          content:
            text/plain:
              schema:
                type: string

Overlay:

overlay: 1.0.0
info:
  title: "..."
  version: 1.0.0
actions:
  # remove the tagged endpoints
  # TODO doesn't work currently `bump-cli@2.9.8`
  - target: $.paths..[?(@.tags && @.tags[*] == 'Enterprise-Only')]
    remove: true

  # remove the top-level tags
  - target: $.tags[?(@.name == 'Enterprise-Only')]
    remove: true

When running:

npx bump-cli@2.9.8 overlay openapi.yml overlay.yaml

I would expect /super/secret not to exist, but it does

[jeremyfiel]

Using this path seems to work directly with jsonpathly but bump did not work according to Jamie.

$.paths..[?(@.tags && @.tags[?(@ == 'Enterprise-only')])]

[jamietanna]

Working with Jeremy, we found that:

overlay: 1.0.0
info:
  title: "..."
  version: 1.0.0
actions:
  # remove the tagged endpoints
  - target: $.paths..[?(@.tags && 'Enterprise-Only' in @.tags)]
    remove: true

  # remove the top-level tags
  - target: $.tags[?(@.name == 'Enterprise-Only')]
    remove: true
  # TODO: check if this solves the pathItem filtering
  # remove empty pathItem objects
  - target: $.paths[*][?(!(@.get))]
    remove: true

Solves it 🚀

[jeremyfiel]

While this is working, the use of in is not spec compliant with RFC9535. Also, the last defined overlay to remove the empty pathItem objects is technically not correct.. It shouldn't need to use the [*] as the filter expression should be directly against the path nodes.

I've filed other issues related to this with valid examples that are failing.

• RFC9535 - Function extensions are not supported ( match, search, count, length, value) atamano/jsonpathly#13
• RFC9535 - filter expression does not return expected results atamano/jsonpathly#14

[jeremyfiel]

Using this path seems to work directly with jsonpathly but bump did not work according to Jamie.

$.paths..[?(@.tags && @.tags[?(@ == 'Enterprise-only')])]

in fact, this doesn't work as mentioned in my issue created on the jsonpathly repo.

[paulRbr]

Hi @jamietanna, Hi @jeremyfiel

Thanks for filling an issue!

The Bump CLI does use the jsonpathly lib to “target” some nodes of the given openapi file. Unfortunately we don't currently have the expertise to improve that lib which is maintained independently @atamano.

I see that you seem to have found a solution to target some operations with a given tag (given @jamietanna's last comment).

If I understand correctly the Bump CLI leaves “empty” path items if all operations are removed from a given path item with an overlay. Is this the remaining outstanding problem you have?

How can we help with the Bump CLI?

[jeremyfiel]

Hey Paul

Bump correctly leaves these in place because they were not targeted to be removed unless the additional overlay action is defined, which is shown by Jamie's definition.

The bigger issue is the package doesn't fully implement RFC9535 and some otherwise valid expressions don't return the expected results. Let's hope some progress can be made by the maintainer.

[jeremyfiel]

you may consider jsonpath-rfc9535 package as an alternative. It seems to process the correct queries without any issue, per the spec.

https://www.npmjs.com/package/jsonpath-rfc9535 cc @P0lip is the maintainer.

[paulRbr]

Thanks @jeremyfiel the package you share does seem good! We'll try it out for a future release of the CLI.