📖 2 min read (~ 300 words).

Alias compatibility

Info

This example runs the other direction — code → spec (swagger generate spec), not spec → code. That code-first workflow is the subject of the go-openapi/codescan site; it lives here only because the repo hosts the example. The rest of this site is spec-first codegen.

The alias-compatibility example shows how a Go type alias is reflected when you generate a spec from Go code, and how the --transparent-aliases flag controls it.

Tip

Source: alias-compatibility/.

The aliases

UserID is a true Go alias (=) of Identifier, not a distinct named type:

// Identifier represents a unique identifier.
type Identifier string

// UserID is an alias to Identifier for user-specific IDs.
type UserID = Identifier

Full source: alias-compatibility/api.go

What the flag does

When swagger generate spec walks this code, the alias can be treated two ways:

  • Default (post-#3227) — UserID appears as its own definition, and User.id references #/definitions/UserID.
  • --transparent-aliases — UserID is not emitted; User.id references #/definitions/Identifier directly (the pre-#3227 behavior).

See the difference by generating both and diffing:

$ swagger generate spec -m -o without-flag.json
$ swagger generate spec -m --transparent-aliases -o with-flag.json
$ diff <(jq . without-flag.json) <(jq . with-flag.json)
  • go-openapi/codescan — the code-first (code → spec) workflow this example belongs to.
  • External types — the spec-first counterpart: binding a schema to an existing Go type.