Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bundle() incorrectly dereferences some literal $ref properties #160

Open
pimterry opened this issue Jan 29, 2021 · 4 comments
Open

Bundle() incorrectly dereferences some literal $ref properties #160

pimterry opened this issue Jan 29, 2021 · 4 comments

Comments

@pimterry
Copy link

Not all $ref properties are actual refs that should be dereferenced. In example values specifically, $ref can be used for a literal field name, and should never be dereferenced (I think? OAI/OpenAPI-Specification#1986 (comment) seems to agree).

This matters unfortunately because GitHub's API spec does exactly that: github/rest-api-description#188. In their components.examples they have:

"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",
              "externalId": null,
              "displayName": "octo-org",
              "members": [
                {
                  "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
                  "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
                  "display": "octocat@github.com"
                },
                {
                  "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
                  "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
                  "display": "hubot@example.com"
                }
              ],
              "meta": {
                "resourceType": "Group",
                "created": "2020-06-09T03:10:17.000+10:00",
                "lastModified": "2020-06-09T03:10:17.000+10:00",
                "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Groups/abcd27f8-a9aa-11ea-8221-f59b2be9cccc"
              }
            },
            {
              "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
              ],
              "id": "5e75bbbb-aa1a-11ea-8644-75ff655cdddd",
              "externalId": null,
              "displayName": "octo-docs-org",
              "members": [
                {
                  "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
                  "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
                  "display": "octocat@github.com"
                }
              ],
              "meta": {
                "resourceType": "Group",
                "created": "2020-06-09T16:28:01.000+10:00",
                "lastModified": "2020-06-09T16:28:01.000+10:00",
                "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Groups/5e75bbbb-aa1a-11ea-8644-75ff655cdddd"
              }
            }
          ]
        }
      },

The $ref properties within this are literal values, as they would be returned by the API. Bundling this spec fails, like so:

> const parser = require('@apidevtools/swagger-parser')
> parser.parse('./api.github.com.json').then(s => parser.bundle(s))
ResolverError: Error downloading https://api.github.com/scim/v2/enterprises/octo-corp/Users/aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5 
HTTP ERROR 403

Not sure if this applies to cases other than examples, but I wouldn't be that surprised.

@philsturgeon
Copy link
Member

Hey @pimterry, did you get a chance to dig into this at all, or is it still an issue? There's a loooooot of issues here and I'm trying to help, but maintenance of this repo isn't my job and I know you're smart! :D

@pimterry
Copy link
Author

Hey @philsturgeon! I haven't dug into this any further, but I've just tested with the same code from above, and I can confirm it's still an issue: bundling the official GitHub OpenAPI spec fails with the same error, because it tries to dereference a $ref that's part of an example response, not a real usable reference.

@pimterry
Copy link
Author

The prerequisite for implementing this (APIDevTools/json-schema-ref-parser#249) just shipped!

We could now fix this here, we just need to pass an excludedPathMatcher option that can recognize valid examples paths in an OpenAPI document (i.e. match any path to an Example Object) so we treat those literally and skip dereferencing them.

@pimterry
Copy link
Author

Just to update this: this is still an issue, and the current behaviour is certainly incorrect, but it fell off my todo list because GitHub changed their spec instead so it no longer applies to my use case.

If anybody else is interested in this, feel free to pick it up! The new json-schema-ref-parser feature from APIDevTools/json-schema-ref-parser#249 should be sufficient to do this, you just need to use that to define which parts of an OpenAPI spec should not be dereferenced automatically (i.e. which parts are literal examples).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants