search

aj-foster / open-api-generator

Open API code generator for Elixir
MIT License
103 stars 14 forks source link

Doesn't support `$ref` fields with just relative file paths #65

Open doughsay opened 2 months ago

doughsay commented 2 months ago

Hey, I'm pretty new to Open API, so there could be things I'm just misunderstanding, but according to this doc here: https://swagger.io/specification/#reference-object the $ref field looks like it can take on multiple forms.

e.g. it could be a "Reference Object":

"$ref": "#/components/schemas/Pet"

a "Relative Schema Document":

"$ref": "Pet.json"

or a combination of both? a "Relative Documents With Embedded Schema":

"$ref": "definitions.json#/Pet"

this code here though: https://github.com/aj-foster/open-api-generator/blob/main/lib/open_api/reader/state.ex#L172 seems to assume that the ref will always contain a "#", so when I run it on this spec it crashes. This is the spec I'm using, just to play around with this and get a feel for this library: https://github.com/SpaceTradersAPI/api-docs/tree/v2.1.0

It uses refs of the middle form, i.e. relative paths to files without a # in them.

doughsay commented 2 months ago

I'm just now realizing that maybe the problem is that this library only supports yaml specs, and this one is json? I've heard "json is just a subset of yaml", but I've also heard to be very dubious of this claim 😅

aj-foster commented 2 months ago

Hello there 👋🏼

Thanks for reporting this, and thank you for the example spec. Although it's unusual for individual schemas to be broken out into separate files like this, it's perfectly allowable, and I failed to handle it correctly. I'm working on a fix, however there are a few issues to deal with along the way.

The first fix is simple: I assumed that all refs would have the # character, which is wrong. In the future we'll use a default path of #/, meaning the root of the document, in case one isn't provided.

After that, it looks like the generator doesn't correctly deal with schemas that are located in separate files. I'm still working on the fix for this.