Alias rendering

A Go type alias (type Price = Money) is, to the Go type system, literally the same type as its target. codescan’s default is to treat it that way: at a use site the alias dissolves to its target, producing no definition of its own.

// Money is the underlying model.
//
// swagger:model
type Money struct {
	// Cents is the amount in cents.
	Cents int64 `json:"cents"`

	// Currency is the ISO currency code.
	Currency string `json:"currency"`
}

// Price is a Go alias of Money. By default an alias is a Go implementation
// detail: at use sites it dissolves to its target, producing no definition of
// its own.
type Price = Money

// Invoice references Price; the field resolves to Money.
//
// swagger:model
type Invoice struct {
	// Total is the invoice total.
	Total Price `json:"total"`
}

{
  "type": "object",
  "title": "Invoice references Price; the field resolves to Money.",
  "properties": {
    "total": {
      "$ref": "#/definitions/Money"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases"
}

Invoice.total is typed Price, but the field resolves straight to #/definitions/Money — Price itself never appears.

Exposing an alias as a first-class entity

This is an advanced, rarely-needed case. To keep the alias name in the spec (its own definition that other schemas $ref), annotate the alias with swagger:model. Two top-level options then govern how that first-class alias definition is shaped:

• default (expand) — the alias definition is a structural copy of the target.
• RefAliases: true — the alias definition is a $ref chain to the target ({"$ref": "#/definitions/Money"}), preserving the alias name at use sites.
• TransparentAliases: true — aliases dissolve to their target everywhere, overriding the per-declaration annotation (use sites become $ref to the target, as in the default-dissolve example above).

For the precise per-mode contract and the canonical witnesses, see the swagger:alias reference and the fixtures/enhancements/alias-calibration-embed golden trio.