Allow excluding certain paths from dereferencing

[pimterry]

This is the first step towards fixing APIDevTools/swagger-parser#160 and thereby github/rest-api-description#188.

In OpenAPI, examples must be interpreted literally. For example, a response could include this examples field to illustrate a possible HTTP JSON response body:

"examples": {
  "scim-enterprise-group-list": {
    "value": {
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
      ],
      "totalResults": 2,
      "itemsPerPage": 2,
      "startIndex": 1,
      "Resources": [
        {
          "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
          ],
          "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
          "displayName": "octo-org",
          "members": [
            {
              "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
              // v Note the $ref here
              "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
              "display": "octocat@github.com"
            }
          ]
        }
      ]
    }
  }
}

(This is a smaller version of a real example from GitHub's OpenAPI spec)

In this case, this is showing an example where a response really will contain a $ref field - it's not a ref to an external resource in the spec, and it shouldn't ever be dereferenced.

The OpenAPI spec on example objects here describes this as an "Embedded literal example" and this discussion goes into more detail.

The only way to handle cases like this is to allow callers of dereference to stop dereferencing at certain points within a schema's structure. This PR adds a excludedPathsMatcher dereference option, which allows the caller to provide a callback that can do this.

The example test shows a quick & dirty approach to how the OpenAPI problem could be solved with this new option. It's not rigorous (really it should be checking against a large list of possible paths from the root) but it shows you the general idea and produces the correct result given the example included here.

[philsturgeon]

@pimterry hey Tim, this looks fantastic. Can you do a quick example in docs/options.md so folks know how to use this feature?

[pimterry]

Can you do a quick example in docs/options.md so folks know how to use this feature?

Done 👍

[alfetopito]

Hi there!
I'm quite interested in this feature.
Any chance to have it released?

BTW, it already shows up in the docs but it's not part of the latest NPM package version 9.0.9

[github-actions]

🎉 This PR is included in version 9.1.0 🎉

The release is available on:

• npm package (@release-v9.1.x dist-tag)
• GitHub release

Your semantic-release bot 📦🚀