APIDevTools
Error: Token "Components" Does Not Exist
Although we didn't make any code changes, sometime around November 22nd 2021, we started getting an error when compiling our API documentation: Token "components" does not exist. However, the components file is still visible, accessible, and hasn't been changed in almost a year.
Is there anything you'd suggest to help troubleshoot this issue? Thanks for your help.
$ tree -C -L 1 ./
./
├── endpoints
├── schemas
└── apispec.yml
$ swagger-cli --version
4.0.4
$ swagger-cli bundle --type yaml apispec.yml
Token "components" does not exist.
The endpoints and schemas directory contains path and schema definitions. We successfully preview the documentation with both Swagger UI and Redoc, so I presume our specification is valid. Still, I can't figure out the reason for that error.
Any assistance would be appreciated.
EDIT: Just realized it my spec does not validate...
$ swagger-cli validate --type yaml ./xapi-spec.yml
Token "components" does not exist.
I was able to solve the issue. The problem was that we had some:
$ref: '#/components/schemas/MyCookie'
But #/ will try to find components in the current file. As soon as changed to things like this, it worked:
$ref: '../cookies.yml#/components/schemas/MyCookie'
or
$ref: '../params.yml#/components/schemas/MyParam'
This way, we are referencing components in a specific file and not in "the current file".
It would be nice if the behaviour in swagger-cli would match the preview behaviour, as in.
That requires deciding on whether to interpret $ref: #/ as a reference inside the current file or whether to interpret it as a reference inside the current document (which is the merged result).
The latter is apparently the behaviour used by Swagger UI and IMHO makes a lot more sense as it makes the component files more file-path agnostic.
