📖 5 min read (~ 1000 words).

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.

Annotated Go
// 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"`
}

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

#/definitions/Invoice
{
  "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"
}

Full source: docs/examples/shaping/aliases/testdata/invoice.json

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:

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

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

// Fee is a FIRST-CLASS alias: the swagger:model annotation keeps the alias name
// in the spec instead of dissolving it to Amount.
//
// swagger:model
type Fee = Amount

// Receipt references the alias, not the target.
//
// swagger:model
type Receipt struct {
	// Charge is the fee charged.
	Charge Fee `json:"charge"`
}

Full source: docs/examples/shaping/aliases-firstclass/firstclass.go

Two top-level options then govern how that first-class alias definition is shaped. The panes below are the same package scanned under each.

Default — the alias definition is a copy

Fee is emitted as a structural duplicate of Amount, and Receipt.charge points at the alias:

Default (expand)
{
  "Amount": {
    "type": "object",
    "title": "Amount is the underlying model.",
    "properties": {
      "cents": {
        "description": "Cents is the amount in cents.",
        "type": "integer",
        "format": "int64",
        "x-go-name": "Cents"
      },
      "currency": {
        "description": "Currency is the ISO currency code.",
        "type": "string",
        "x-go-name": "Currency"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases-firstclass"
  },
  "Fee": {
    "description": "Fee is a FIRST-CLASS alias: the swagger:model annotation keeps the alias name\nin the spec instead of dissolving it to Amount.",
    "type": "object",
    "properties": {
      "cents": {
        "description": "Cents is the amount in cents.",
        "type": "integer",
        "format": "int64",
        "x-go-name": "Cents"
      },
      "currency": {
        "description": "Currency is the ISO currency code.",
        "type": "string",
        "x-go-name": "Currency"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases-firstclass"
  },
  "Receipt": {
    "type": "object",
    "title": "Receipt references the alias, not the target.",
    "properties": {
      "charge": {
        "$ref": "#/definitions/Fee"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases-firstclass"
  }
}

Full source: docs/examples/shaping/aliases-firstclass/testdata/expand.json

RefAliases: true
{
  "Amount": {
    "type": "object",
    "title": "Amount is the underlying model.",
    "properties": {
      "cents": {
        "description": "Cents is the amount in cents.",
        "type": "integer",
        "format": "int64",
        "x-go-name": "Cents"
      },
      "currency": {
        "description": "Currency is the ISO currency code.",
        "type": "string",
        "x-go-name": "Currency"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases-firstclass"
  },
  "Fee": {
    "description": "Fee is a FIRST-CLASS alias: the swagger:model annotation keeps the alias name\nin the spec instead of dissolving it to Amount.",
    "$ref": "#/definitions/Amount"
  },
  "Receipt": {
    "type": "object",
    "title": "Receipt references the alias, not the target.",
    "properties": {
      "charge": {
        "$ref": "#/definitions/Fee"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases-firstclass"
  }
}

Full source: docs/examples/shaping/aliases-firstclass/testdata/refaliases.json

RefAliases: true — the alias definition is a $ref chain

The right pane above: Fee becomes {"$ref": "#/definitions/Amount"}. One shape, two names — the alias survives at use sites without duplicating the target’s properties. Prefer this over the default whenever the alias is genuinely a synonym: a copy drifts the moment the target changes.

TransparentAliases: true — use sites dissolve

{
  "Amount": {
    "type": "object",
    "title": "Amount is the underlying model.",
    "properties": {
      "cents": {
        "description": "Cents is the amount in cents.",
        "type": "integer",
        "format": "int64",
        "x-go-name": "Cents"
      },
      "currency": {
        "description": "Currency is the ISO currency code.",
        "type": "string",
        "x-go-name": "Currency"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases-firstclass"
  },
  "Fee": {
    "description": "Fee is a FIRST-CLASS alias: the swagger:model annotation keeps the alias name\nin the spec instead of dissolving it to Amount.",
    "type": "object",
    "properties": {
      "cents": {
        "description": "Cents is the amount in cents.",
        "type": "integer",
        "format": "int64",
        "x-go-name": "Cents"
      },
      "currency": {
        "description": "Currency is the ISO currency code.",
        "type": "string",
        "x-go-name": "Currency"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases-firstclass"
  },
  "Receipt": {
    "type": "object",
    "title": "Receipt references the alias, not the target.",
    "properties": {
      "charge": {
        "$ref": "#/definitions/Amount"
      }
    },
    "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/aliases-firstclass"
  }
}

Full source: docs/examples/shaping/aliases-firstclass/testdata/transparent.json

Receipt.charge now points straight at #/definitions/Amount: the alias is gone from the reference graph.

Warning

Note what did not happen: Fee is still emitted. TransparentAliases governs how an alias renders at its use sites, not whether an annotated declaration produces a definition — so with ScanModels you get a Fee definition that nothing references. Add PruneUnusedModels to drop it, or simply do not annotate an alias you intend to dissolve.

The three modes at a glance:

Fee definitionReceipt.charge
default (expand)copy of Amount$ref: Fee
RefAliases: true$ref: Amount$ref: Fee
TransparentAliases: truecopy of Amount, unreferenced$ref: Amount

Wider calibration lives in the fixtures/enhancements/alias-calibration-embed golden trio.

Note

Most APIs never need first-class aliases — prefer naming a real swagger:model type over aliasing one. Reach for RefAliases / TransparentAliases only when you specifically need to control whether an alias name survives in the output.

The swagger:alias annotation is deprecated and has no effect — alias rendering is governed by the plain Go alias plus these options, or by swagger:model for a first-class definition.