How to use custom extensions while reusing definitions?

[lcbm]

Note: made it work with a workaround; answer in the comments 🥵

Hi, everyone! 😄

Thanks in advance for any tips and suggestions!

I'm trying to reuse some of the definitions and, at the same time, make sure its possible for other developers to use the following custom extensions:

• x-nullable
• x-omitempty
• x-go-name
• x-go-custom-tag

I understand that the example below represents incorrect usage of $ref (everything at the $ref level is ignored); but that's the behavior I would be aiming for 👇

definitions:
  MyObjectType:
    type: object
    x-nullable: false
    properties:
      number:
        $ref: "#/definitions/Number"
        x-nullable: false
        x-omitempty: true
        x-go-custom-tag: "bson:\"number,omitempty\""
  MyOtherObjectType:
    type: object
    x-nullable: false
    properties:
      number:
        $ref: "#/definitions/Number"
        x-nullable: true
        x-omitempty: false
        x-go-custom-tag: "bson:\"Number\""
  Number:
    type: string
    enum:
      - one
      - two
      - three

With Anchors (&) and Aliases (*)

I managed to use anchors and aliases, as below, but I would actually like Number to be a type and MyObjectType to use that, and not string.

x-types:
  number: &NUMBER
    - one
    - two
    - three
   
  definitions:
      number:
        type: string
        enum: *NUMBER
        x-nullable: false
        x-omitempty: false
        x-go-custom-tag: "bson:\"number,omitempty\""

   // number
   // Enum: [one two three]
   Number string `json:"number" bson:"number,omitempty"`                <------ anchor

   // number
   NumberType Number `json:"number,omitempty" bson:"number,omitempty"`  <------ $ref

With x-go-type

The next approach I found was using x-go-type, but we are actually looking forward to having these models generated by swagger from the spec and not the other way around or having to implement and reference too many models in swagger using x-go-type.

x-types:
  id: &ID
    type: "ID"
    import:
      package: "github.com/redacted/redacted/pkg"
    hints:
      kind: string
      noValidation: false
      nullable: false
    embedded: false
    
definitions:
  MyObjectType:
    type: object
    x-nullable: false
    properties:
      id:
        type: string
        x-go-type: *ID
        x-go-name: ID
        x-go-custom-tag: "bson:\"_id,omitempty\""
        x-nullable: false
        x-omitempty: true
      id2:
        type: string
        x-go-type: *ID
        x-go-name: ID2
        x-go-custom-tag: "bson:\"id2\""
        x-nullable: true
        x-omitempty: false

// MyObjectType my object type
//
// swagger:model MyObjectType
type MyObjectType struct {

   // ID
   ID pkg.ID `json:"id,omitempty" bson:"_id,omitempty"`

   // ID 2
   ID2 *pkg.ID `json:"id2" bson:"id2"`
}

Merge Key (<<)

This is the closest I got so far; although it generates Number, type interface{} is used in MyObjectType 😄

definitions:
  number: &NUMBER
    type: string
    enum:
    - one
    - two
    - three

  MyObjectType:
    type: object
    x-nullable: false
    properties:
      source:
        <<: *NUMBER
        x-go-name: Sauce
        x-go-custom-tag: "bson:\"source,omitempty\""
        x-nullable: false
        x-omitempty: false

// MyObjectType my object type
//
// swagger:model MyObjectType
type MyObjectType struct {

	// num
	Num interface{} `json:"source" bson:"source,omitempty"`
}

Reproducing

Add the following to any of the yamls above:

swagger: "2.0"
info:
 version: version
 title: title
paths: {}

Generate models from the spec:

$ swagger generate model --spec=<FILE_NAME>.yml

[lcbm]

Was able to make it work with a workaround. Really wish we could use it with $ref tho 😢

// MyObjectType my object type
//
// swagger:model MyObjectType
type MyObjectType struct {

	// ID
	ID *pkg.ID `json:"id,omitempty" bson:"f,omitempty"`

	// num
	Num Number `json:"number" bson:"number"`
}

This is what makes it work 👇

x-go-type:
  type: "Number"
  
# equivalent to
x-go-type:
    type: "Number"
    import:
      package:
      alias:
    hints:
      kind: <whatever default is>
      noValidation: false
      nullable: <whatever default is>
    embedded: false

swagger.yml

swagger: "2.0"

info:
 version: version
 title: title

paths: {}

x-types:
  id: &ID
    type: "ID"
    import:
      package: "github.com/redacted/redacted/pkg"
      alias: pkg
    hints:
      kind: string
      noValidation: false
      nullable: false
    embedded: false

definitions:
  MyObjectType:
    type: object
    x-nullable: false
    properties:
      id:
        type: string
        x-go-type: *ID
        x-go-name: ID
        x-go-custom-tag: "bson:\"f,omitempty\""
        x-nullable: true
        x-omitempty: true
      number:
        type: string
        x-go-type:
          type: "Number"
        x-go-name: Num
        x-go-custom-tag: "bson:\"number\""
        x-nullable: false
        x-omitempty: false
  Number:
    type: string
    enum:
      - one
      - two
      - three

On a separate note, one could set default values values for custom extensions at the definition level and overwrite them at the property level 😄

definitions:
  MyObjectType:
    type: object
    x-nullable: false
    properties:
      default:
        type: string
        x-go-type:
          type: "Number"
      custom:
        x-go-type:
          type: "Number"
        x-go-custom-tag: "bson:\"custom\""
        x-nullable: false
        x-omitempty: false
  Number:
    type: string
    x-go-name: Number
    x-go-custom-tag: "bson:\"default\""
    enum:
      - one
      - two
      - three

[lcbm]

Figured out another downside to this approach: in the Swagger UI, x-go-types are rendered as whatever they are hinted to be, not the actual type.