contiamo
[FR]: Support path-based $refs when resolving OpenAPI Specs
Is your feature request related to a problem? Please describe.
I'd like to use this on OpenAPI Specs that use the $ref feature to refer to definitions from other files, such that large APIs can be split into multiple files for reuse/readability purposes.
Presently, this library only supports $refs within the same file.
https://github.com/contiamo/restful-react/blob/45d0ef61b5b0894d3f7da7c66e6fd1c1c98e62b1/src/scripts/import-open-api.ts#L93
Describe the solution you'd like
Ability to use multi-file OpenAPI specs, since I'm trying to making them with https://stoplight.io/studio
Describe alternatives you've considered
I wonder if there are any OpenAPI tools that can rewrite a spec that uses path based $refs such that all the content gets imported into 1 file under the "components" key, for the benefit of tools that aren't designed to work with multi-file OpenAPI specifications such as this one.
Additional context Add any other context or screenshots about the feature request here.
- Related reading about Refs: https://swagger.io/docs/specification/using-ref/
Workaround obtained via my coworker: swagger-cli stitched together my files, e.g.
swagger-cli bundle my_open_api_spec.yaml -t yaml > resolved_api_spec.yaml
https://www.npmjs.com/package/swagger-cli
Thanks for the workaround and the tool 👌 This feature is not really a priority for us (since we just have single file specs for now 😬) but it's definitely something I would like to have!
Just some little things to keep in mind, we need to support the github import flow, and avoid types duplications, this is why I keep this feature to later, to keep the generator "simple" 😉
Noticed today that the latest https://www.npmjs.com/package/swagger-parser might work better than swagger-cli, since it's compatible with external files, but unlike swagger-cli, supports working with circular references (which was necessary for working with recursive data types)
I am experiencing this same error, but not sure why. I tried generating types for 4 different APIs. 2 succeeded , 2 failed. The OpenAPI specs for these files were generated with the same tooling and they are very similar in what they do with $refs. I just cant figure out why the different outputs. Plan net and Carin were success, while uscore and usdf failed. Any ideas?
Hi @fhirfly
Indeed, restful-react generator do not support external $ref like this one:
You need to bundle your spec before feeding the generator:
$ npx @redocly/openapi-cli bundle uscore.yaml --output uscore-bundled.yaml
$ restful-react import --file uscore-bundled.yaml --output uscore.tsx
(This is just an example using https://github.com/Redocly/openapi-cli , but any kind of bundler can work)