Redoc: Declaring two routes with external schemas results in "Invalid reference token: properties" error

[huksley]

Error

If I create two or more routes which use external file schemas I am getting error
when I use redoc.standalone.js
but not when I use redoc-cli

Invalid reference token: properties

Full stack trace:

Something went wrong...
Invalid reference token: properties

Stack trace

e.exports<[2]</o.get@http://localhost:8080/redoc/redoc.standalone.js:56:17165
e@http://localhost:8080/redoc/redoc.standalone.js:56:25500
e@http://localhost:8080/redoc/redoc.standalone.js:56:26331
e.exports<[10]</n.sampleObject/<@http://localhost:8080/redoc/redoc.standalone.js:56:23529
e.exports<[10]</n.sampleObject@http://localhost:8080/redoc/redoc.standalone.js:56:23444
e@http://localhost:8080/redoc/redoc.standalone.js:56:26617
e@http://localhost:8080/redoc/redoc.standalone.js:56:25532
e.exports<[10]</n.sampleObject/<@http://localhost:8080/redoc/redoc.standalone.js:56:23529
e.exports<[10]</n.sampleObject@http://localhost:8080/redoc/redoc.standalone.js:56:23444
e@http://localhost:8080/redoc/redoc.standalone.js:56:26617
e.exports<[5]</n.sample@http://localhost:8080/redoc/redoc.standalone.js:56:20803
Gt</e.prototype.generateExample@http://localhost:8080/redoc/redoc.standalone.js:101:57365
e@http://localhost:8080/redoc/redoc.standalone.js:101:56790
e/this.mediaTypes<@http://localhost:8080/redoc/redoc.standalone.js:101:57793
e@http://localhost:8080/redoc/redoc.standalone.js:101:57741
Kt@http://localhost:8080/redoc/redoc.standalone.js:101:58506
get@http://localhost:8080/redoc/redoc.standalone.js:101:60520
get@http://localhost:8080/redoc/redoc.standalone.js:101:37251
Zl</t.prototype.render/<@http://localhost:8080/redoc/redoc.standalone.js:121:50711
el@http://localhost:8080/redoc/redoc.standalone.js:77:106602
wl@http://localhost:8080/redoc/redoc.standalone.js:77:88955
vl@http://localhost:8080/redoc/redoc.standalone.js:77:88880
sl@http://localhost:8080/redoc/redoc.standalone.js:77:85822
Yo/<@http://localhost:8080/redoc/redoc.standalone.js:77:45132
t.unstable_runWithPriority@http://localhost:8080/redoc/redoc.standalone.js:85:3465
qo@http://localhost:8080/redoc/redoc.standalone.js:77:44841
Yo@http://localhost:8080/redoc/redoc.standalone.js:77:45077
Vo@http://localhost:8080/redoc/redoc.standalone.js:77:45012
nl@http://localhost:8080/redoc/redoc.standalone.js:77:82542
enqueueSetState@http://localhost:8080/redoc/redoc.standalone.js:77:49709
x.prototype.setState@http://localhost:8080/redoc/redoc.standalone.js:69:1468
Un</t.prototype.load/</<@http://localhost:8080/redoc/redoc.standalone.js:101:75226
s/</<@http://localhost:8080/redoc/redoc.standalone.js:22:2545
s/<@http://localhost:8080/redoc/redoc.standalone.js:22:2650
a@http://localhost:8080/redoc/redoc.standalone.js:22:1418

ReDoc Version: 2.0.0-rc.18
Commit: cd9fd618

How to reproduce

git clone https://github.com/huksley/redoc-schemas-bug
npm install
npm run serve # no error when loading http://localhost:8080 in browser
npm run start # error

Versions

node: 12.11.4
redoc-cli: 0.9.2
redoc: 2.0.0-rc.18

[huksley]

This comment are relevant:
https://github.com/Redocly/redoc/issues/1000#issuecomment-526566523

[huksley]

As far as I understand redoc-serve merges all referenced schemas into one single spec.json document and serves it as
http://localhost:8080/spec.json

[DavidVaness]

I encountered the same bug, any news about this?

[RomanHotsiy]

I can reproduce the issue on my side. I will investigate it but looks like it is caused by some race-condition because of the order of separate files resolution..

This is most likely caused by the underlying bundling lib we use in Redoc.

Please, bundle you schemas ahead of time for now. We are going to replace our bundling library soon.

[Blacklands]

I just ran into the same problem. (Wish I could give more details, but I'm unsure which changes exactly even caused it to happen, everything was fine so far and then it suddenly broke.)

I don't think I can even bundle the spec beforehand, because the issue is also occurring with openapi-cli's preview-docs function. If I were to bundle the spec before running that, it couldn't watch the changes I'm making to the original files, so the function would be essentially useless...

@RomanHotsiy Is this replacement of the bundling library going to make it into the v2.0 release? I'm on v2.0.0-rc.31, and so far this is still happening.

Also, should I open a separate issue about this over on the openapi-cli repo? It seems it's the same underlying cause, so I'm not sure if that would add anything.

[RomanHotsiy]

@Blacklands yes, we plan to include openapi-cli into redoc.

Would be great if you can open an issue against openapi-cli. We are finishing a huge rewrite of openapi-cli and already published an alpha. If you can try it against alpha would be amazing! Try @redocly/openapi-cli@next

[Blacklands]

Just wanted to report that with the rewritten version of openapi-cli, this issue seems to be gone! (For me, at least.)
I'm using the latest 1.0.0-beta.3 version (had to wait until preview-docs is implemented again, since that's what I'm primarily using), and I did not run into any Invalid reference token errors (nor any other errors like that) again.
I tried to replicate what I had tried to do when I last ran into the error (mostly splitting up the spec I'm working on into even more files and subdirectories), but everything is working fine now. All the commands of the tool are working.
(Sorry that I can't give more specific information.)

[SimonPallam]

The bug happens whenever you try to reference the same file twice in the same object.
example here with amount.json:
js "type": "object", "properties": { "amount": { "$ref": "amount.json", "description": "The instructed amount and applied currency for the instructed amount" }, "pendingAmount": { "$ref": "amount.json", "description": "The amount of money left from an authorisation" },

[Blacklands]

@SimonPallam
That's interesting. I'm doing that in many, many places, and I don't have the bug (anymore).
The only obvious differences I can see right now is that I am using YAML and not JSON, and that I'm "wrapping" most of the $refs into anyOf/allOf blocks so I can have a description (the example that you posted there is actually not valid OpenAPI 3.0, Reference Objects cannot have siblings - even though it may work with Redoc).

[SimonPallam]

@Blacklands
Thanks, so I have been testing all cases:

• It works in YAML as it is
• removing siblings and using allOf doesn't fix it in when in JSON