oapi-codegen
oapi-codegen copied to clipboard
deepmap
Adding support for external refs
Hey thanks for writing this library, I know it's still early days for this library but I was wondering if there were any plans to add support for external refs?
e.g.
`$ref: "../resource.yml/#components/schemas/Hello"`
I had a play around enabling SwaggerLoader.IsExternalRefsAllowed but ran into this
Only local document components are supported
Happy to contribute a patch but before doing so was wondering if there was any reason in particular for not supporting this feature.
We use kin-openapi to parse and resolve swagger specs, and it doesn't seem to support that.
We use kin-openapi to parse and resolve swagger specs, and it doesn't seem to support that.
Riiight, I was under the impression SwaggerLoader.IsExternalRefsAllowed flattened out all the refs but looking through the source that's not the case :D
I have a proposed solution to at least some of the external refs issues here:
https://github.com/deepmap/oapi-codegen/pull/48
The primary issue is that external refs should reside in a different package. The codegen is designed to write a single file so this cannot be done with one pass. This proposal allows the user to specify the package path for any external refs and use a previous generate stage to generate that package. This is written more for url based refs but this is an approach that may get the ball rolling.
Hi @dannymidnight @deepmap-marcinr @weberr13 I believe external refs are still not supported? As I am getting below error during code gen...
error loading swagger spec: Encountered non-allowed external reference
I can see both this issue and linked PR are in Closed status. Has the project decided not to add this feature?
We are working with amazon eventbridge and dealing with quite a bit schema files. The external refs would allow us to not have to repeat event structure in every file. External refs support would be super handy for us and for many others.
Is there any plans for this to be added or any ideas on workarounds for projects with many schema files that need to reference one another? thanks!
I would be happy to incorporate external references, however, we use the kin-openapi (https://github.com/getkin/kin-openapi) to load our swagger spec, and it simply fails on specs with external refs. So, in order to fix it, I would have to first pre-process your spec, pull down the external refs, merge them in, and then use kin-openapi to parse the combined spec - a giant mess.
The way to do this is to extend kin-openapi to resolve external references. Once kin-openapi supports it, we'll merge it in here asap.
@deepmap-marcinr thanks for the reply.
As a workaround, I am currently experimenting with https://www.npmjs.com/package/swagger-cli as a preprocessor to bundle all external references into a single file first. Then running oapi-codegen on combined spec.
That all seem to be working except codegen fails when schema has additionalProperties: true.
I raised an issue for that: https://github.com/deepmap/oapi-codegen/issues/193
Could you take a look and let me if there's a bug somewhere? Thanks!
Based on the merged contribution of @dududko is this issue ready to be marked as solved?
Nice one @dududko @deepmap-marcinr getting this change in. I just had a play around with the new import-mapping API and it's looking great 👍
One issue I found after adding external references is that now GetSwagger() errors due to IsExternalRefsAllowed being false.
In my case I was able to work around this by loading directly from the swagger file rather than the base64 encoded string however this might not be desired for others.
e.g.
func getSwagger() (*openapi3.Swagger, error) {
loader := openapi3.NewSwaggerLoader()
loader.IsExternalRefsAllowed = true
swagger, err := loader.LoadSwaggerFromFile(path.Join(config.BaseDir, "openapi/openapi.yml"))
if err != nil {
return nil, fmt.Errorf("error loading Swagger: %s", err)
}
return swagger, nil
}
@dannymidnight Thanks for the example, very clear! But openapi yaml files have been removed in my usage, so I can't go with the workaround. I have filed a issue getkin/kin-openapi/issues/286 to discuss whether possible to improve it start from getkin/kin-openapi. Welcome to propose idea for a long-term solution. :)
@wangyoucao577 Please check #320. I added a support for embedding specs and resolving external references. If this approach does not satisfy your needs I'm pretty sure that using this example you will manage to craft something that will suit you.
@dannymidnight I implemented the solution for the limitation that you have found. Please check #320
It's clear we need thorough unit tests for all path concatenation. This breaks frequently, and I blame my inadequate testing. I'll come up with something.
On Thu, Mar 18, 2021 at 4:52 PM Dudko Alexey @.***> wrote:
@dannymidnight https://github.com/dannymidnight I implemented the solution for the limitation that you have found. Please check #320 https://github.com/deepmap/oapi-codegen/pull/320
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/deepmap/oapi-codegen/issues/42#issuecomment-802395309, or unsubscribe https://github.com/notifications/unsubscribe-auth/ALKC5DF63YZLBQZTCB2FBOLTEKG4FANCNFSM4IHPNJDQ .
Note this solution will not work when you have two .yml files pointing to each other like in this issue https://github.com/deepmap/oapi-codegen/issues/621
We solved the external reference problem by using @redocly/cli to combine multiple swagger files. All you have to do is simple. 1 . Combine swagger files using @redocly/cli. 2. Generate code with oapi-codegen based on the combined swagger files Hope this solution will help many people!
