openapi3: allow Extensions next to $ref in SchemaRef

[paulmach]

See https://github.com/getkin/kin-openapi/issues/900 for full details and use-case. If this approach is agreed upon, I can extend to all *Refs (e.g. CallbackRef, ExampleRef, ResponseRef, etc.)

Captures x-order into SchemaRef.Extensions

type: object
properties:
 id:
   $ref: "#/components/schemas/id"
   x-order: 1
 name:
   type: string

Only extensions (those starting with 'x-') are captured. This is because extra attributes are technically not allowed by the spec, but also to maintain the way JSONLookup works. For example:

schemas:
  id:
    type: integer
    x-order: 2
  thing:
    type: object
    properties:
     thing_id:
       $ref: "#/components/schemas/id"
       type: string
       x-order: 1
     name:
       type: string

Doesn't change: thingIDRef.JSONLookup("type") will continue to return "integer" as overriding the type next to the ref is not allowed and bad practice, in my opinion. There could be a use-case for stuff like nullable, but for now I would rather not change the behavior.

Does change: thingIDRef.JSONLookup("x-order"). Today, 2, as it goes back to the $ref definition. After this change it'll be 1 (value next to the $ref).

Does change: Validate() behavior. It's now okay, by default, to have extensions next to the $ref. To change this behavior, use the ProhibitExtensionsWithRef option.

[paulmach]

Oh snap, looks like refs.go is auto generated. Please see if you like this change, then I make the change to refs.sh.

[paulmach]

I made the following changes:

• moved tests in ref_test.go into refs_issue222_test.go and refs_issue247_test.go
• added validation options AllowExtensionsWithRef (default) and ProhibitExtensionsWithRef
• updated refs.sh to generate the code
• add refs_test.sh to generate tests
• reran docs.sh and added refs_test.sh as part of the github workflow.

I think the only "question" is if ref.Extensions should capture ^x- fields or all extra fields. As mentioned above, there could be some impact for "weird" schemas if we capture all fields. I propose to only capture ^x- fields for now as more backwards compatible. We can always change it based on feedback.

[fenollp]

This is great work thank you!

WRT non x-.. in Extensions you're right: let's just keep the x-.. keys in here for now anyway

[paulmach]

I rebased on the latest master. Hoping to get this into the next release.

[paulmach]

Hi @fenollp, I rebased again on the latest master. Hoping to get this into the next release.