openapi3: introduce ReferencesComponentInRootDocument(doc *T, ref componentRef) (string, bool)

[percivalalb]

This MR adds a function (ReferencesComponentInRootDocument) to check if a component reference references the same document or element as another component reference in the root document's #/components/<type>. If it does, it returns the name of it in the form #/components/<type>/NameXXX.

It does this by keeping track of the source file paths of schemas in multi-file'd specs.

This enables the amalgamation of schemas which reference the same underlying model which removes very annoying to use anonymous structs in generated models when using codegen tools like oapi-codegen.

TODO: add MR in oapi-codegen displaying improved model generation. oapi-codegen/oapi-codegen#1573

[fenollp]

Hello!
How about a func that, given a doc and a Schema, returns a *SchemaRef (a ptr under doc) or nil? Would this not cover your use case?

Note: the refs.go file is generated.

[percivalalb]

Hello!

How about a func that, given a doc and a Schema, returns a *SchemaRef (a ptr under doc) or nil? Would this not cover your use case?

Note: the refs.go file is generated.

Yes, if it also returned the name in the #components/schemas/...

Input: doc, Schema
Output: name, SchemaRef

I'll have a look at moving it out of the gen'ed file

[percivalalb]

I've moved the alternations out of the code gen'ed files, sorry I'm still getting familar with the project setup and just thrown everything in the helper file. I'd like to ad some unit tests of couse but hopefully this is more to your liking.

[fenollp]

This is looking pretty good!
Could you re-push the docs? It fails CI.
Also please send your tests away :) And an Example that shows usage of the function.

[percivalalb]

Things to do:

• I think these snippets https://github.com/getkin/kin-openapi/pull/945/files#diff-035b395ae81006bbe6cd7144c686238113762fccdb051ddaef5d507560039ee6R540 which construct the refPath should be moved to a single function in resolveComponent. I believe componentPath should be the value we need already.
• I'm not sure how this plays well with schema's loaded from memory (i.e. no paths)
• Also not sure if it supports external referencing other spec files or URL references
• Update ComponentType so that values are returned in camelCase - currently some of the values are invalid
• Not sure if I should be using path or filepath to join path components. I think some of the uri are from the file system (so os dependant) but others are URLs so use /.
• Need to add unit tests
• Add example usage of function

Heads up I'll be away for 10 days, so I won't be developing this PR for a bit

[percivalalb]

Address most of the bullet points. Where is the best place for the example?

Edit: Added an example to the READMD.md