search

swagger-api / swagger-node

Swagger module for node.js
http://swagger.io
Apache License 2.0
3.97k stars 584 forks source link

$ref relative paths not working #544

Open jnazander opened 6 years ago

jnazander commented 6 years ago

I am running swagger on node.js using swagger-express-mw, and I'm trying to split the huge swagger.yaml file (which is currently over 2000 lines long) into multiple files for easier editing.

Now, in theory this should be a straightforward thing to do - just reference other YAML files using $ref - but in practice this seems far more complicated than it ought to be!. For start, according to the official OpenAPI specification, you're not allowed to put $ref directly under paths: or definitions:. That's a weird restriction, but I can live with that, it's not the main problem.

The main problem is that Swagger doesn't seem to support relative paths in $ref at all! For example, I have the main swagger file as src/api/swagger/swagger.yaml in the same directory I have linkedFile.yaml, which swagger.yaml is supposed to link to using $ref. Simple enough, right? Just add $ref: './linkedFile.yaml' in swagger.yaml? Wrong!

If I run swagger project verify on swagger.yaml, it complains that it cannot find linkedFile.yaml, because it's searching for it in the project's root folder, instead of in src/api/swagger/. If, instead, I link it as $ref: './src/api/swagger/linkedFile.yaml', then the verifier does actually pass, but this approach obviously wouldn't work when actually running the application, because there will be no src folder then. I also can't put the YAMLs into the root folder, because only the files inside src will be built and deployed.

Even if I run swagger project verify while being inside src/api/swagger/, then it still somehow changes the working directory to the project root before running, and still not finds the linked file.

So, what is the point of having the ability to link files using $ref when in practice it doesn't even support specifying YAMLs relative to the current file?

xbl commented 6 years ago

+1

jnazander commented 6 years ago

I did find a workaround from the swagger-tools developer: https://github.com/apigee-127/swagger-tools/issues/227 (bottom posts) I tried it, it works fine, but as for fixing the actual bug, it looks like they aren't gonna do it anytime soon.

tomderudder commented 5 years ago

+1

Hyprnx commented 3 years ago

+1 same problem on Python