Descriptions beside a $ref

When a struct field’s only decoration is a description and its Go type resolves to a named model (a $ref), JSON Schema draft 4 cannot carry a sibling description next to a $ref. Options.DescWithRef decides what happens to that description.

// Address is a referenced model.
//
// swagger:model
type Address struct {
	// Street is the street line.
	Street string `json:"street"`
}

// Person references Address through a field whose only decoration is a
// description.
//
// swagger:model
type Person struct {
	// Home is where the person lives.
	Home Address `json:"home"`
}

Full source: docs/examples/shaping/descref/descref.go

By default the description is dropped (a bare $ref); with DescWithRef it is preserved by wrapping the $ref in a single-arm allOf:

Default — description dropped

{
  "description": "Person references Address through a field whose only decoration is a\ndescription.",
  "type": "object",
  "properties": {
    "home": {
      "$ref": "#/definitions/Address"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/descref"
}

Full source: docs/examples/shaping/descref/testdata/off.json

DescWithRef: true

{
  "description": "Person references Address through a field whose only decoration is a\ndescription.",
  "type": "object",
  "properties": {
    "home": {
      "description": "Home is where the person lives.",
      "allOf": [
        {
          "$ref": "#/definitions/Address"
        }
      ],
      "x-go-name": "Home"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/descref"
}

Full source: docs/examples/shaping/descref/testdata/on.json

codescan.Run(&codescan.Options{
    Packages:    []string{"./..."},
    ScanModels:  true,
    DescWithRef: true,
})

Info

When the field carries more than a description — a validation override or a user-authored extension — the allOf wrapper is emitted regardless of this flag, because the override would otherwise be lost. DescWithRef only governs the description-only case.