Usage as a library

The most direct way to use codescan from your own Go program is to import it and call Run.

This supports various use-cases such as a generator, a go:generate step, or a test that keeps your spec in sync with the source.

Install

go get github.com/go-openapi/codescan

codescan exposes a deliberately small surface: a single Run function and an Options struct.

func Run(opts *Options) (*spec.Swagger, error)

Annotate your source

Annotations are special comments following the go-swagger convention (swagger:meta, swagger:route, swagger:model, swagger:parameters, swagger:response, …).

A package-level swagger:meta block carries the top-level metadata of the spec:

// Package petstore Petstore API
//
// A tiny pet store, used to demonstrate codescan annotations: the package
// comment is a `swagger:meta` block carrying the top-level metadata of the
// generated specification (title, description, version, base path, …).
//
//	Schemes: https
//	Version: 1.0.0
//	BasePath: /v1
//
//	Consumes:
//	- application/json
//
//	Produces:
//	- application/json
//
// swagger:meta

Full source: docs/examples/petstore/doc.go

A swagger:model annotation turns a Go struct into a definition; field-level comments become validations and descriptions:

// Pet is a single pet in the store.
//
// swagger:model Pet
type Pet struct {
	// The id of the pet.
	//
	// required: true
	// minimum: 1
	ID int64 `json:"id"`

	// The name of the pet.
	//
	// required: true
	// min length: 1
	Name string `json:"name"`

	// The tags associated with this pet.
	Tags []string `json:"tags,omitempty"`
}

Full source: docs/examples/petstore/pet.go

Run the scanner

Point codescan at the package(s) to scan. Patterns are relative go list-style patterns, resolved against WorkDir:

opts := &codescan.Options{
	WorkDir:    workDir,                // module root to resolve patterns from
	Packages:   []string{"./petstore"}, // relative package pattern
	ScanModels: true,                   // also emit definitions for swagger:model types
}

doc, err := codescan.Run(opts)
if err != nil {
	return nil, err
}

Full source: docs/examples/basic/scan.go

The returned *spec.Swagger is the standard github.com/go-openapi/spec document — marshal it to JSON or YAML, feed it to a validator, or merge it onto an existing spec via Options.InputSpec.

Options worth knowing

Those are the ones a first call tends to need. Everything else — alias handling, $ref siblings, naming, doc-comment cleanup, the loader, the go environment — is in the Options reference, which gives each field with its command-line and configuration-file spellings beside it. The godoc is the normative source.

Dependencies

Code loading relies by default on the go toolchain and this requires go to be installed.

To alleviate this constraint, you may want to use the pure-go ToolchainFreeLoader loader in your options, so programs that build on top of codescan don’t shell out a go list command.

Next

• Scan a package — the whole of the above as one runnable, test-covered example.
• Usage as a headless CLI — the same scan without writing a program, for a build or a pipeline.
• Tutorials — the worked, by-concept version of the above, each with the spec it produces.
• Annotation index — every annotation at a glance, linked to its example and its full reference.
• Maintainers reference — the complete annotation vocabulary, keywords, and grammar.

Usage as a headless CLI

genspec is the ordinary way to run codescan without writing a program: point it at annotated Go source, get a Swagger 2.0 document. Everything the library can be told is a flag, the document goes to standard output or to -output, and what the scan observed goes to standard error.

Install

go install github.com/go-openapi/codescan/cmd/genspec@latest

# scan the module in the current directory, document to standard output
genspec

# somewhere else, narrowed, to a file, and checked
genspec -workdir ../my-api -output swagger.yaml -validate ./internal/api/...

The packages are Go patterns, resolved against -workdir. Naming none scans ./....

Two streams, never mixed

The document goes to standard output; diagnostics go to standard error, colored when that is a terminal. Nothing is written to standard error when there is nothing to say. So the obvious pipeline is safe:

genspec > swagger.json
genspec | jq '.definitions | keys'

This is the command’s doing, not the library’s: codescan itself never writes to either stream. Every observation it makes — a dropped construct, a rename, a prune — is passed to the command through a callback, and genspec renders those callbacks as lines you can read.

Choosing the output

auto is why the common cases need no -format at all:

genspec -output swagger.yaml     # YAML, because of the name
genspec -output swagger.json     # JSON
genspec > swagger.json           # JSON
genspec -compact                 # JSON with no indentation

YAML is derived from the JSON rendering, which costs key order: the document comes out alphabetical rather than in the order the spec types declare. Same information, a different diff against a hand-written file.

-input is the place for everything a scanner cannot know — the host, the security definitions, a hand-written path the annotations do not describe. The scan is merged on top of it; see Overlaying a spec.

Diagnostics

-fail-on covers what -validate found as well as what the scan observed: they reach the reader as one stream, so a threshold that saw only half of it would be a trap rather than a policy. It defaults to never, because a scan that emits warnings is the ordinary case, and a command that failed the build over one would mostly teach people to stop reading them.

Validating: whether the document is legal Swagger 2.0

A scan that reports nothing is not a promise that the document it produced is valid. The scanner diagnoses what is wrong with your annotations; whether the result is a legal Swagger 2.0 document is a separate question. Pass -validate to answer it:

genspec -validate -output swagger.yaml ./internal/api/...

It checks the rendered JSON rather than the document in memory, so what is validated is exactly what was written — including whatever the round trip through JSON did to it. The check is go-openapi/validate, the same one behind swagger validate.

Findings arrive through the same stream as the scan’s own, because to a reader they are the same kind of news about the same document. Each is located by the JSON pointer the validator recorded as it walked the spec, so it names the node rather than a line:

ERROR | paths./orders.post.parameters.1.in in body is required at=/paths/~1orders/post/parameters/1

A finding about something the document lacks — no info block, no paths — has an empty pointer, which is a location in RFC 6901 and not the absence of one. It is reported as the whole document rather than printed as nothing:

ERROR | info in body is required at=(the whole document)
genspec: the specification is not valid: 1 finding(s)

Warnings and errors both come out. Only errors make the document invalid: a warning — an unused definition, say — is worth saying and is not a verdict, and whether it fails the command is -fail-on’s business rather than the validator’s.

An invalid document exits 4, and that outranks -fail-on’s 3: it is the more specific answer. The document is still written either way, so you can look at what was rejected.

Exit status

A specification is written whenever one could be produced, so a non-zero status says what was wrong with the document rather than meaning nothing came out.

An invalid document outranks -fail-on: it is the more specific answer.

Configuring it once

Anything that can be a flag can be preset in a .codescan.yaml, found by searching upwards from wherever you are — so a project configures itself once and the command is run bare:

scan:
  exclude-tags: [internal]

document:
  format: yaml
  compact: true

diagnostics:
  validate: true
  fail-on: warning

The options naming a path are not among them — -workdir, -output, -input — because a file found by searching upwards belongs to the tree being scanned, and that tree must not choose where the command reads or writes. They are typed:

genspec -workdir ./api -output swagger.yaml ./...

Anything typed on the command line wins over it. The file’s full contract — where it is looked for, what sections exist, -config and --no-config — is in Setting an option.

The scan itself

genspec -h lists every flag. They fall into the four families a configuration file uses as its sections:

• which code (scan) — -workdir, the positional patterns, -build-tags, -include / -exclude, -include-tags / -exclude-tags, -exclude-deps
• what it is built as (go) — -goos, -goarch, -goflags, -gowork, -goexperiment. Each decides what compiles, and so what the document says; each is a flag rather than inherited state, so a scan is reproducible
• how it is read (load) — -loader, -stub-stdlib, -compiled-dependencies
• what is emitted (emit) — -scan-models, -prune-unused-models, the alias and allOf knobs, -skip-extensions, the naming and doc-comment knobs

They are the library’s own options under their own names: a flag is the kebab-case of the field it writes, without exception. The Options reference gives each one with its field, its default and what it does.

Without a Go toolchain

genspec-wasi is the same scan with nothing behind it: it depends on nothing beyond the library, runs no subprocess, and cross-compiles to wasip1/wasm. Use it where genspec cannot go — a sandbox, a CI image with no Go in it, a WebAssembly runtime — and it is the engine behind the Playground.

go install github.com/go-openapi/codescan/cmd/genspec-wasi@latest
genspec-wasi -workdir ../my-api ./internal/api/...

It carries the same scan flags, but drops genspec’s document and diagnostics surface: no -validate, no -fail-on, no -color. In their place it offers an envelope.

An envelope for a program

Document on stdout and prose on stderr suits a person or a pipeline. It is not enough for a program: prose carries a position only in the sense that one is printed in it, and provenance — which Go construct produced this spec node — has nowhere to go at all. -format=json writes one object instead:

{
  "spec": { "swagger": "2.0", "definitions": { "doc": {} } },
  "diagnostics": [
    {"severity": "hint", "code": "validate.dropped-ref-sibling",
     "message": "field \"for\": description dropped …",
     "file": "models/m.go", "line": 12, "col": 5}
  ],
  "provenance": [
    {"pointer": "/definitions/doc", "file": "models/m.go", "line": 8, "col": 6}
  ],
  "runtime": { "sys": 390070272, "heapAlloc": 369098752, "collections": 2 }
}

Positions are relative to -workdir, so a caller holds models/pet.go and need not know what the guest called it; a position outside the module stays absolute, which is how a consumer tells the two apart. Provenance covers anchors — type declarations, fields, values, route and meta blocks — sorted by pointer, so the same scan produces the same bytes. Under -format=json standard error stays clean, so the envelope is safe to read from a pipe.

Experimental, inheriting the status of Options.OnProvenance.

Under a WASI runtime

GOOS=wasip1 GOARCH=wasm go build -o genspec-wasi.wasm ./cmd/genspec-wasi

# wasmtime — <host>::<guest>
wasmtime run --dir "$PWD::$PWD" genspec-wasi.wasm -workdir "$PWD" ./...

# wazero — <host>:<guest>, no separator
wazero run -mount="$PWD:$PWD" genspec-wasi.wasm -workdir "$PWD" ./...

Two things a guest cannot work out for itself:

• -goos / -goarch must be passed. Left alone they default to the platform the scanner is running on, which inside a guest is wasip1 — which silently drops every _linux.go file and produces a different document than the same scan run natively.
• GOROOT and the module cache are found by path. Nothing in a WASI environment can ask the go command where they live, so if the scan needs them they must be mounted and named through the environment.

How much of the host to expose

The real choice is how much of the host the guest may see. Measured on the petstore fixture under wasmtime:

Memory is usually the binding constraint rather than time — 681 MB for a fixture this small is more than a browser tab can host.

-export-data reads dependencies from the export data the compiler already produced instead of parsing and type-checking them. It costs a fraction of the time with no loss of fidelity, the types being the compiler’s own; it is valid only for the toolchain that produced it. -stub-stdlib fabricates standard-library types from the names the code selects, needs no GOROOT at all, and is the one option here that is not failsafe: recognition by identity survives (time.Time is still a date-time) but structure does not, so json.RawMessage stops rendering as a byte array and nothing is seen to implement encoding.TextMarshaler. Every synthesized import raises a scan.synthesized-import diagnostic, so the loss is never silent.

Full detail, including a build that embeds its own export data and needs nothing mounted but the project, is in the genspec-wasi README.

Next

• Setting an option — the configuration file in full, and which spelling wins.
• Options reference — every flag with the library field it writes.
• Usage as a terminal UI — the same scan with the source and the document side by side, while you write the annotations.

Usage as a terminal UI

genspec-tui is an interactive terminal front-end for codescan.

It puts the Go source on the left, the Swagger document that source produces on the right, and the scanner’s diagnostics underneath — all regenerated every time you save.

Its reason to exist is that loop: change an annotation, save, see the spec change.

Predicting what an annotation will produce is the slow part of writing one, and reading a golden file after a build is a poor substitute for watching the node appear.

Beyond the loop, it links the two sides together. You can ask “which Go declaration produced this node?” or “what did this field turn into?” and get an answer by position — not by matching names by eye.

Install and run

go install github.com/go-openapi/codescan/cmd/genspec-tui@latest

# scan the module in the current directory
genspec-tui

# or point it somewhere, and narrow the scope
genspec-tui -workdir ../my-api ./internal/models/... ./internal/api/...

The selected packages are a positional argument, resolved against -workdir; naming none scans ./....

-packages, taking one comma-separated list, is the older spelling and still works

The TUI registers the same flags as the other commands — one per field of codescan.Options — and reads the same .codescan.yaml, so a session starts where your build leaves off. The flags decide the first scan; almost all of them are also live toggles, below.

The ones worth knowing at the point of starting a session:

Note that -scan-models defaults to on here, where the library’s ScanModels defaults to off. A spec you are browsing in order to see what your types became has little to show without them.

A second group settles what gets built, and how it is loaded — the environment go list would read, plus codescan’s own loader:

Everything the flags set is also a live toggle. Press o for the options popup, space to flip a row, Esc to apply — the spec re-renders on close, which makes the popup the fastest way to find out what a knob such as EmitRefSiblings actually changes. Rows that only bite in combination say so: PruneUnusedModels reads (needs ScanModels) until that one is on.

Being in both places is the point: you can start a session one way and change your mind without restarting. The one option with no route in at all is InputSpec (overlay mode).

Scanning: the edit-save-see loop

The left pane starts as the source tree; Enter opens a file into the viewer, which is read-only and navigable. i turns it into an editor, Ctrl-S saves, a file watcher notices the write, and the spec re-renders. Editing outside the TUI works just as well — disk is the source of truth, and F5 re-reads the open file (asking first, if you have unsaved edits to lose).

A rescan keeps you where you were. The spec cursor is restored to the same node, not the same line number, so a definition that appears above what you are reading does not slide you somewhere else. If the node is gone — you deleted the type — the cursor falls back to its nearest surviving ancestor.

Both panes are syntax-highlighted by the same palette, and in the source viewer a comment gets three classes rather than one, because in a spec generator a comment is not uniformly commentary:

What lights up as a keyword comes from the parser’s own table, so aliases (min → minimum) and letter case are free — and what is highlighted is what the parser will actually act on.

Tracking: from a spec node back to the code

f turns on a persistent link between panes. The pane you pressed it in is the driver and keeps focus; the others mirror it on every cursor move, centring and highlighting the linked line. A SPEC ▸ SOURCE badge names the direction and the target it resolved to.

It works in three directions — spec → source, source → spec, and a diagnostic to both. Esc, a second f, changing focus, or starting to edit all leave it.

Two indexes, rebuilt on every render, meet at a JSON pointer: one maps each rendered spec line to the pointer of the node on it, the other maps pointers back to Go source positions through codescan’s OnProvenance callback. That is why the answer is exact rather than a name match.

The gutter marks which lines actually lead somewhere, so you can see what is navigable without probing for it:

Only exact anchors are marked. Nearly every line resolves to something through its nearest anchored ancestor, so marking those would dot the whole document and tell you nothing.

F3 steps through the places the node under the cursor is referenced, wrapping; shift+F3 goes back; Enter follows a $ref to its definition.

Diagnostics: what the scanner made of your annotations

Whether your annotations were understood is a different question from whether the document they produced is well formed, and the pane at the bottom answers the first one. Under a one-line severity tally it lists everything the scan observed, in source order, each row carrying its severity’s colour so the pane can be read for red at a glance. Enter jumps to the source line a finding names and focuses it; f makes the selection drive both other panes at once.

Findings are also drawn at the site: the token a diagnostic names is underlined in the severity’s colour, in the source viewer itself. The pane tells you what and where; the underline tells you which token, without leaving the line you are reading.

Marks are re-derived on every rescan, so they never outlive the finding that produced them.

Validating: whether the document is legal Swagger 2.0

v runs the generated document through go-openapi/validate and lists what it finds in a validation tab of the diagnostics pane. V switches between that tab and the scan’s own findings.

This is the second of the two questions above, and answering both is why they are tabs rather than one list: a scan can be perfectly clean and still produce something a consumer rejects.

They also track different things. A scan diagnostic carries a source position, so it drives the source pane. A validation finding carries only a JSON pointer, so Enter and f there drive the spec pane and nothing else.

The tab exists only once you have pressed v, and a rescan retires it: those findings judged a document that has just been replaced, and a list of complaints about a spec that no longer exists invites navigating to nodes that may have moved or gone. Press v again.

What a scan cost: m

m opens a card describing the run that just finished — how long it took, what it allocated, what it left live, and how much the process holds from the OS.

Time and memory are split between scanning and rendering the document, and recapped as ratios on the split line, because the question a reader arrives with is usually which phase is this? The two can disagree sharply, which is why both are there.

Allocated counts everything the run churned through, garbage included; retained counts what it left behind. A scan that allocates half a gigabyte and retains a few megabytes is not the same problem as one that keeps what it takes, and one number could not tell you which you have.

Two things the card says about itself, worth repeating: the window is process-wide, so the redraw loop and the file watcher are in the figures; and a rescan holds two documents at once, so the retained figure reads high by about one. That is arithmetic, not a leak.

A scalar cannot say who spent it, which is what -profile is for. Start the session with it and each scan is profiled as well as timed, so the card also reports where the CPU went and what allocated it, by function and per phase:

genspec-tui -profile -workdir ../my-api

# every allocation counted rather than sampled every 512 KiB — accurate, and slow
genspec-tui -profile -mem-profile-rate=1 -workdir ../my-api

CPU is charged to the call of ours that led there, not to the leaf frame. A leaf answers “what was executing”, which for this program is mostly the allocator and the collector — true, and nothing anyone can act on. Charged our way, a row names the boundary where codescan hands the work to somebody else’s code, and covers everything under it.

Profiling is not free, and the card says so rather than letting you compare across runs by accident: under -profile the scalars at the top carry the profiler’s own overhead and its collections, while the tables below exclude them. The card scrolls when it outgrows the terminal (↑↓/jk, PgUp/PgDn, Home/End).

It names the .pprof files it wrote and the go tool pprof commands that open them. All three flags are addressed in the profile section of a .codescan.yaml.

Looking up an annotation

With the viewer’s navigation line on a comment carrying a swagger: directive, K shows what that annotation does: its syntax, a one-line summary, and what may be written in its body. Clicking the directive does the same.

K because it is vim’s “look up what is under the cursor”, and what LSP clients bind hover to. It reads the buffer, so it works on an annotation you are still typing — which is when you want it.

The popup covers all twenty swagger: annotations, and each entry names the family of keywords its body accepts rather than listing them: there are far too many individual keywords for a popup to be the right place for them. For those, and for worked examples of every annotation, the reference on this site is the long form:

• Annotations — one page per annotation, with grammar and live examples
• Keyword reference — every keyword, grouped by the family it belongs to

Keys worth knowing

The binding surface is context-dependent — f follows from three different panes, Enter opens a file in the tree but follows a $ref in the spec — so the header carries a standing h: help banner.

Everything else — the per-pane bindings, the editor, the popups — is in the h overlay and in the module README, which documents the internals as well.

Worth knowing before you rely on it

These limits are deliberate; the TUI reports them rather than guessing.

• Not every node has source. codescan anchors code-detail nodes — type declarations, fields, values, route and meta blocks — and finer nodes resolve to their nearest anchored ancestor. A node with no anchored ancestor at all was not produced from code (an InputSpec overlay node, say); the follower holds position and says so instead of jumping somewhere plausible.
• Positions are as of the last scan. With unsaved edits in the buffer every anchor below the edit has shifted, so follow shows a STALE badge. Saving triggers a rescan and clears it.
• $ref resolution is a site index, not a resolver. Local #/… refs are followable; a ref into another file or a URL is reported as external rather than chased.
• Some keys are terminal-dependent. shift+F3 and ctrl+arrow rely on sequences most modern emulators send and a few (notably inside a default tmux) do not. Where they are missing nothing misfires — there is simply no previous-reference key, and no resize keys.
• Split sizes last for the session only. They survive rescans and terminal resizes, but not a restart. The TUI does read a .codescan.yaml — but what a file can set is flags, and where the splits sit is not one of them.

The module README carries the full list.

What’s next

• Usage as a library — drive the same scanner from your own program, a go:generate step, or a test.
• Usage as a headless CLI — the same scan in a build, with the settings you converged on here.
• Options reference — every knob the o popup toggles, and what it does to the document.
• Tutorials — annotate a package from meta to definitions, with the TUI open beside you.

Setting options

There are three ways to set the same knob — a Go field, a command-line flag, a key in a .codescan.yaml — where the file is looked for, what may be in it, and which spelling wins when they disagree.

opts := &codescan.Options{
	WorkDir:    workDir,                // module root to resolve patterns from
	Packages:   []string{"./petstore"}, // relative package pattern
	ScanModels: true,                   // also emit definitions for swagger:model types
}

doc, err := codescan.Run(opts)
if err != nil {
	return nil, err
}

genspec -name-from-tags form,json -prune-unused-models ./internal/api/...

scan:
  exclude-tags: [internal]

emit:
  scan-models: true
  name-from-tags: [form, json]

document:
  format: yaml
  compact: true

diagnostics:
  validate: true
  fail-on: warning

Which spelling wins

Flags win over config. That holds for a flag typed with the value it already had:

# false, even where the file says scan-models: true
genspec -scan-models=false

It is decided by asking the flag set which flags were actually seen, not by comparing values against defaults — which is what makes the rule statable in one sentence instead of one per flag.

Everything the file sets lands through the same path a command-line argument takes, so a value is parsed and validated exactly once, and a file cannot express anything an argument could not. A malformed value is refused the same way, naming the file.

Between the two, the ordinary defaults apply — with one deliberate divergence: the commands default -scan-models to true where the library field is false. A command asked to produce a specification and handed a package of annotated models should produce their definitions.

One file, several commands

There is one file name for the whole family, not one per command: a project configuring a scan has configured it for all of them. What tells them apart is the sections.

• A section a command does not recognize is skipped, not rejected — that is how genspec-tui’s profile: settings sit beside genspec’s document: in the same file.
• A key inside a section it does know must name one of its flags. That is what makes a typo an error rather than a setting that quietly never applied.

Run genspec -verbose to see which file was read and which keys were skipped.

What has no flag

Four options are not values a command line can carry.

The command owns them instead — and each of the commands makes its own choice about how, which is why they are not in the shared table:

Two more fields carry no flag because nothing should be reaching for them: DescWithRef and Debug are deprecated.

Next

• Options reference — every field, with its flag and its section.
• Usage as a headless CLI — the flags genspec adds of its own.

Options reference

codescan.Options is the single configuration struct passed to codescan.Run.

The zero value is a valid configuration — every flag defaults to false, every slice/map to nil, every numeric tunable to its built-in default. You set only what you need.

This page is the field-by-field catalogue, and serves the commands as much as the library: Flag gives the text to type, and Section gives the .codescan.yaml section addressing it — the key inside that section is the flag without its dash. See Setting an option for the rules those two columns follow, and for the handful of options that are nobody’s flag.

The godoc is the normative source; each field here links to the how-to guide that shows it on real input where one exists.

Inputs & scope

What gets loaded and which packages and types are in play. See Scope & discovery.

Loading & the go environment

Where the package graph comes from, and which platform it is built for. These change the emitted spec the way BuildTags does — by deciding which files each package is made of — or change what the scan needs in order to run at all.

They are options rather than inherited process state so that a scan is reproducible: a value picked up from whatever shell started it is easy to apply on one code path and forget on another.

Which loader, and why

Three ways to get a package graph. The table below catalogues the fields; this is how to choose between them.

Standard loader — the default. Loads your code with the Go toolchain, through golang.org/x/tools/go/packages. Maintained by the Go team, and the reference for how patterns and imports resolve: where either of the others disagrees with it, the other one is wrong. Requires Go installed, and uses the build cache.

Pure-Go loader (ToolchainFreeLoader) — loads your code with codescan’s own reimplementation. Cuts memory by roughly 45%, and needs no go command and no subprocess. It still reads GOROOT/src for the standard library, so it wants a Go installation — just not a runnable toolchain. Modules only. It uses no build cache, so cold costs what warm costs: about level with the standard loader on a warm cache, roughly 30% faster on a cold one, and the only choice whose cost does not depend on cache state. Usually the right pick for CI.

Compiled dependencies (CompiledDependencies) — the standard loader taking dependency types from the compiler’s export data instead of reading their source. It produces the same document either way — whatever the spec needs out of a dependency is read at the moment it is needed — and on a warm build cache it is the fastest by a wide margin, and several times smaller.

It must compile the dependency closure rather than type-check it, so on a cold cache it is an order of magnitude slower and writes a large build cache. Reach for it where the cache is warm by construction — your own machine, a watch loop, a pipeline that restores its cache — and leave it off where a clean checkout is the norm, as a CI runner usually is. Code that does not compile is not a reason to avoid it: such a load is retried from source automatically.

Two further options drop the GOROOT requirement altogether, for environments with no Go installation at all — a WASI guest, a browser. StubStdlib synthesizes the standard library, and pays for the reach in fidelity: a fabricated type has the right name and no structure. ExportData serves dependencies from a blob you prepare in advance, and pays in preparation instead — the types are the compiler’s own, but the blob is only valid for the toolchain that produced it, and a package it does not cover falls back to source and then to synthesis.

Names & references

How definitions are named and how $refs render. See Names & $refs.

Titles & descriptions

The human-readable text the spec carries. See Titles & descriptions.

Field types, formats & extensions

How an individual property renders. See Field types & formats.

Diagnostics & observability

Channels for what the scan observed; these do not change the output spec.

The two callbacks are how the commands report: genspec renders diagnostics on standard error, and genspec-wasi -format=json carries both in its envelope for a program to read.

See also

• Setting an option — the flag and key rules the two middle columns follow, and which spelling wins.
• Annotations — the swagger:* vocabulary the scanner reads from comments.
• Keyword reference — the keyword: value forms inside annotation bodies.
• Shaping the output — task-oriented how-tos that put these options to work on real input.

README

codescan

A Go source code scanner that produces Swagger 2.0 (OpenAPI 2.0) specifications from annotated Go source files.

Supports Go modules (since go1.11).

Announcements

• 2025-04-19: large package layout reshuffle
  • the entire project is being refactored to restore a reasonable level of maintainability
  • the only exposed API is Run() and Options.

Status

API is stable.

Import this library in your project

go get github.com/go-openapi/codescan

Basic usage

import (
  "github.com/go-openapi/codescan"
)

swaggerSpec, err := codescan.Run(&codescan.Options{
  Packages: []string{"./..."},
})

See getting started for a worked example.

Change log

See https://github.com/go-openapi/codescan/releases.

Licensing

This library ships under the Apache-2.0 license.

See the license NOTICE, which recalls the licensing terms of all the pieces of software on top of which it has been built.

Other documentation

• All-time contributors
• Contributing guidelines
• Maintainers documentation
• Code style

LICENSE

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

Scan a package

This tutorial scans a tiny annotated “petstore” package and produces a Swagger 2.0 spec. It is the worked version of Usage as a library — start here, then take one concept at a time from the pages that follow.

The annotated API

A package-level swagger:meta block sets the top-level metadata:

// Package petstore Petstore API
//
// A tiny pet store, used to demonstrate codescan annotations: the package
// comment is a `swagger:meta` block carrying the top-level metadata of the
// generated specification (title, description, version, base path, …).
//
//	Schemes: https
//	Version: 1.0.0
//	BasePath: /v1
//
//	Consumes:
//	- application/json
//
//	Produces:
//	- application/json
//
// swagger:meta

Full source: docs/examples/petstore/doc.go

A swagger:route registers a path and ties it to a response:

// swagger:route GET /pets pets listPets
//
// Lists all the pets in the store.
//
// responses:
//
//	200: petsResponse

Full source: docs/examples/petstore/pet.go

A swagger:model struct becomes a definition, with field comments driving validations:

// Pet is a single pet in the store.
//
// swagger:model Pet
type Pet struct {
	// The id of the pet.
	//
	// required: true
	// minimum: 1
	ID int64 `json:"id"`

	// The name of the pet.
	//
	// required: true
	// min length: 1
	Name string `json:"name"`

	// The tags associated with this pet.
	Tags []string `json:"tags,omitempty"`
}

Full source: docs/examples/petstore/pet.go

Running the scan

ScanPetstore builds the Options and calls codescan.Run:

opts := &codescan.Options{
	WorkDir:    workDir,                // module root to resolve patterns from
	Packages:   []string{"./petstore"}, // relative package pattern
	ScanModels: true,                   // also emit definitions for swagger:model types
}

doc, err := codescan.Run(opts)
if err != nil {
	return nil, err
}

Full source: docs/examples/basic/scan.go

The generated spec

Marshalling the returned *spec.Swagger to JSON yields the document below — the meta block became the top-level info / basePath, the swagger:route became the /pets path, and the swagger:model became the Pet definition:

{
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "schemes": [
    "https"
  ],
  "swagger": "2.0",
  "info": {
    "description": "A tiny pet store, used to demonstrate codescan annotations: the package\ncomment is a `swagger:meta` block carrying the top-level metadata of the\ngenerated specification (title, description, version, base path, …).",
    "title": "Petstore API",
    "version": "1.0.0"
  },
  "basePath": "/v1",
  "paths": {
    "/pets": {
      "get": {
        "tags": [
          "pets"
        ],
        "summary": "Lists all the pets in the store.",
        "operationId": "listPets",
        "responses": {
          "200": {
            "$ref": "#/responses/petsResponse"
          }
        }
      }
    }
  },
  "definitions": {
    "Pet": {
      "type": "object",
      "title": "Pet is a single pet in the store.",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "description": "The id of the pet.",
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "x-go-name": "ID"
        },
        "name": {
          "description": "The name of the pet.",
          "type": "string",
          "minLength": 1,
          "x-go-name": "Name"
        },
        "tags": {
          "description": "The tags associated with this pet.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "x-go-name": "Tags"
        }
      },
      "x-go-package": "github.com/go-openapi/codescan/docs/examples/petstore"
    }
  },
  "responses": {
    "petsResponse": {
      "description": "petsResponse is the list of pets returned by listPets.",
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/Pet"
        }
      }
    }
  }
}

Full source: docs/examples/basic/testdata/swagger.json

This JSON is not hand-written: it is a golden file the example’s test regenerates and compares on every run (UPDATE_GOLDEN=1 go test ./...). Because the example is ordinary, test-covered Go, go test ./docs/examples/... keeps the page honest — if the scanner’s output changes, CI fails before the documentation can go stale.

Model definitions

A definitions entry is the most common thing you ask codescan to produce. This page walks the annotations that create and shape one, from the plain swagger:model struct to the per-type overrides. Each pane pairs the annotated Go (left) with the exact fragment the scanner emits (right) — both come from the test-covered docs/examples/concepts/models package.

For the exhaustive rule on any annotation below, follow its link to the Maintainers reference.

swagger:model

swagger:model publishes a Go struct as a definition. Field doc comments become property descriptions; json tags drive the property names; the Go type drives the JSON-Schema type / format. Well-known standard-library types resolve automatically — a time.Time field, for instance, is published as {type: string, format: date-time}.

UUIDs are recognised two different ways, and both publish {type: string, format: uuid}:

• by type identity — the standard-library uuid.UUID introduced in Go 1.27, matched on its import path and name, so nothing else can be mistaken for it;
• by type name — any other type named UUID (case-insensitively) that marshals as text, which covers github.com/google/uuid, gofrs/uuid, strfmt.UUID and the like.

The name-based rule is a heuristic and stays available whichever Go version you build with. Either way an explicit swagger:strfmt on the type wins, so you can always overrule the recognition.

// Pet is a single pet in the store.
//
// swagger:model
type Pet struct {
	// ID is the unique identifier.
	ID int64 `json:"id"`

	// Name is the pet's display name.
	Name string `json:"name"`

	// Tags categorise the pet.
	Tags []string `json:"tags,omitempty"`
}

{
  "type": "object",
  "title": "Pet is a single pet in the store.",
  "properties": {
    "id": {
      "description": "ID is the unique identifier.",
      "type": "integer",
      "format": "int64",
      "x-go-name": "ID"
    },
    "name": {
      "description": "Name is the pet's display name.",
      "type": "string",
      "x-go-name": "Name"
    },
    "tags": {
      "description": "Tags categorise the pet.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "x-go-name": "Tags"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

A swagger:model that nothing else references appears in definitions only when you scan with Options.ScanModels (the -m flag). See When the scanner emits a type.

swagger:strfmt

swagger:strfmt <name> marks a named string type as a custom format. The type does not become its own definition — instead, every field typed by it renders as {type: string, format: <name>}.

// MAC is a hardware address rendered as a colon-separated hex string.
//
// swagger:strfmt mac
type MAC string

func (m MAC) MarshalText() ([]byte, error)  { return []byte(m), nil }
func (m *MAC) UnmarshalText(b []byte) error { *m = MAC(b); return nil }

// Device exposes a strfmt-typed field: wherever MAC appears it renders inline
// as {type: string, format: mac}.
//
// swagger:model
type Device struct {
	// Addr is the hardware address.
	Addr MAC `json:"addr"`
}

{
  "description": "Device exposes a strfmt-typed field: wherever MAC appears it renders inline\nas {type: string, format: mac}.",
  "type": "object",
  "properties": {
    "addr": {
      "description": "Addr is the hardware address.",
      "type": "string",
      "format": "mac",
      "x-go-name": "Addr"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

Add swagger:model to the strfmt type to opt it into a first-class definition ({type: string, format: <name>}) that fields $ref instead of inlining — the general swagger:model ⇒ definition + $ref rule.

swagger:enum

swagger:enum <name> collects the type’s const values. When a model field references the type, the property carries the enum array and an x-go-enum-desc extension built from the per-value doc comments. (The enum type is reachable, and so emitted, only because a model field points at it.) A bare swagger:enum on the type declaration works too — the name is inferred.

// Priority is the urgency level on a task.
//
// swagger:enum Priority
type Priority string

const (
	// PriorityLow is for tasks that can wait.
	PriorityLow Priority = "low"
	// PriorityMedium is the default.
	PriorityMedium Priority = "medium"
	// PriorityHigh is for tasks that must run soon.
	PriorityHigh Priority = "high"
)

// Task is a unit of work carrying an enum-typed field. Referencing Priority
// from a model is what makes the enum reachable, and so emitted.
//
// swagger:model
type Task struct {
	// Priority is the task's urgency.
	Priority Priority `json:"priority"`
}

{
  "description": "Task is a unit of work carrying an enum-typed field. Referencing Priority\nfrom a model is what makes the enum reachable, and so emitted.",
  "type": "object",
  "properties": {
    "priority": {
      "description": "Priority is the task's urgency.\nlow PriorityLow is for tasks that can wait.\nmedium PriorityMedium is the default.\nhigh PriorityHigh is for tasks that must run soon.",
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "x-go-enum-desc": "low PriorityLow is for tasks that can wait.\nmedium PriorityMedium is the default.\nhigh PriorityHigh is for tasks that must run soon.",
      "x-go-name": "Priority"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

Here the values inline on the referencing field. Add swagger:model to the enum type to make it a first-class definition (carrying the enum array) that fields $ref — again the swagger:model ⇒ definition + $ref rule.

Enums have more to them than a string const block: iota and computed members, what decides the emitted type / format, and the inline form parameters and headers take. They get their own page — Enumerations.

swagger:allOf

Embedding base types under swagger:allOf composes a schema. Each embedded base becomes a $ref arm of the allOf; the struct’s own (non-embedded) fields form a final inline arm. That last arm is inline rather than a $ref because those fields are new to this type — they belong to no existing definition to point at. Here Dog embeds two bases (Animal, Tagged) and adds breed, producing three arms: two $refs and one inline object.

// Animal is one abstract base.
//
// swagger:model
type Animal struct {
	// Kind discriminates the animal.
	Kind string `json:"kind"`
}

// Tagged is a second reusable base.
//
// swagger:model
type Tagged struct {
	// Tags label the resource.
	Tags []string `json:"tags"`
}

// Dog composes two base models plus its own fields: each embedded base becomes
// a $ref arm of the allOf, and the struct's own (non-embedded) fields — which
// are new and cannot be a $ref — form the final inline arm.
//
// swagger:model
type Dog struct {
	// swagger:allOf
	Animal

	// swagger:allOf
	Tagged

	// Breed is the dog's breed.
	Breed string `json:"breed"`
}

{
  "description": "Dog composes two base models plus its own fields: each embedded base becomes\na $ref arm of the allOf, and the struct's own (non-embedded) fields — which\nare new and cannot be a $ref — form the final inline arm.",
  "allOf": [
    {
      "$ref": "#/definitions/Animal"
    },
    {
      "$ref": "#/definitions/Tagged"
    },
    {
      "type": "object",
      "properties": {
        "breed": {
          "description": "Breed is the dog's breed.",
          "type": "string",
          "x-go-name": "Breed"
        }
      }
    }
  ],
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

When the base also declares a discriminator, this composition becomes a Swagger 2.0 type hierarchy — see Polymorphic models.

swagger:type

swagger:type <type> overrides the type codescan would infer. Here a [16]byte field is published as a string.

// ULID is a 128-bit identifier stored as bytes but rendered as a string.
//
// swagger:type string
type ULID [16]byte

// Token carries a field whose inferred type is overridden, inline.
//
// swagger:model
type Token struct {
	// ID renders as a string despite its [16]byte Go type.
	ID ULID `json:"id"`
}


// RawID is a custom 16-byte identifier — an array under the hood, so left to
// itself a field of this type would render as an array of integers.
type RawID [16]byte

// Coupon overrides the type of a single field directly on the field doc — no
// wrapper-type annotation. Code publishes as a bare string while RawID is left
// untouched everywhere else it appears.
//
// swagger:model
type Coupon struct {
	// Code is an opaque identifier published as a string.
	//
	// swagger:type string
	Code RawID `json:"code"`

	// Amount is the discount in cents.
	Amount int64 `json:"amount"`
}

{
  "type": "object",
  "title": "Token carries a field whose inferred type is overridden, inline.",
  "properties": {
    "id": {
      "description": "ID renders as a string despite its [16]byte Go type.",
      "type": "string",
      "x-go-name": "ID"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

swagger:type is an inline directive: it renders the chosen type in place and never emits a $ref. The value is a scalar type (string, integer, number, boolean, object, or a Go builtin like int64), []T for an array of an inlined type, inline to expand the field’s own Go type, or a known type name to inline that type. array is deprecated in favour of inline / []T, and file is rejected (use swagger:file). When combined with swagger:strfmt, the type wins and the format is kept only if compatible — see the reference.

The override also works on an individual field doc — no wrapper-type annotation. Here Code is published as a string while its RawID type is left untouched everywhere else:

// RawID is a custom 16-byte identifier — an array under the hood, so left to
// itself a field of this type would render as an array of integers.
type RawID [16]byte

// Coupon overrides the type of a single field directly on the field doc — no
// wrapper-type annotation. Code publishes as a bare string while RawID is left
// untouched everywhere else it appears.
//
// swagger:model
type Coupon struct {
	// Code is an opaque identifier published as a string.
	//
	// swagger:type string
	Code RawID `json:"code"`

	// Amount is the discount in cents.
	Amount int64 `json:"amount"`
}

{
  "description": "Coupon overrides the type of a single field directly on the field doc — no\nwrapper-type annotation. Code publishes as a bare string while RawID is left\nuntouched everywhere else it appears.",
  "type": "object",
  "properties": {
    "amount": {
      "description": "Amount is the discount in cents.",
      "type": "integer",
      "format": "int64",
      "x-go-name": "Amount"
    },
    "code": {
      "description": "Code is an opaque identifier published as a string.",
      "type": "string",
      "x-go-name": "Code"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

swagger:name

swagger:name <name> overrides the JSON property name a field or method renders as. It works on a struct field (overriding the json: tag / Go field name) and on an interface method. It is most useful on interface methods, which publish one property per nullary method and cannot carry a json tag: below, StructType() would default to structType, and the annotation publishes it as jsonClass instead.

// Car is exposed as a schema via its method set. Interface methods cannot carry
// a json tag, so by default each property takes the camelCased method name;
// swagger:name overrides that where the default is not what you want.
//
// swagger:model
type Car interface {
	// Maker is the manufacturer. With no override the property is the
	// camelCased method name, "maker".
	Maker() string

	// StructType is the polymorphic class. Without the override the property
	// would be "structType"; swagger:name publishes it as "jsonClass".
	//
	// swagger:name jsonClass
	StructType() string
}


// Account shows the universal name: keyword renaming model struct fields. The
// same keyword used on parameters and response headers also sets a property key
// here, winning over a json tag, the legacy swagger:name annotation, and the Go
// field name.
//
// swagger:model
type Account struct {
	// Bal has no json tag; the keyword sets the property key directly.
	//
	// name: balance
	Bal float64

	// Currency carries both naming forms; the keyword wins over the
	// legacy annotation and the json tag.
	//
	// name: currencyCode
	// swagger:name legacyCurrency
	Currency string `json:"currency"`
}

{
  "description": "Car is exposed as a schema via its method set. Interface methods cannot carry\na json tag, so by default each property takes the camelCased method name;",
  "type": "object",
  "properties": {
    "jsonClass": {
      "description": "StructType is the polymorphic class. Without the override the property\nwould be \"structType\"; swagger:name publishes it as \"jsonClass\".",
      "type": "string",
      "x-go-name": "StructType"
    },
    "maker": {
      "description": "Maker is the manufacturer. With no override the property is the\ncamelCased method name, \"maker\".",
      "type": "string",
      "x-go-name": "Maker"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

The name: keyword does the same on a model property — and, being the universal form, with the same syntax you would use on a parameter or header. Here it names a tag-less field directly, and on a field that also carries a json: tag and a legacy swagger:name, the keyword wins (name: > swagger:name > json: tag > Go field name):

// Account shows the universal name: keyword renaming model struct fields. The
// same keyword used on parameters and response headers also sets a property key
// here, winning over a json tag, the legacy swagger:name annotation, and the Go
// field name.
//
// swagger:model
type Account struct {
	// Bal has no json tag; the keyword sets the property key directly.
	//
	// name: balance
	Bal float64

	// Currency carries both naming forms; the keyword wins over the
	// legacy annotation and the json tag.
	//
	// name: currencyCode
	// swagger:name legacyCurrency
	Currency string `json:"currency"`
}

{
  "description": "Account shows the universal name: keyword renaming model struct fields. The\nsame keyword used on parameters and response headers also sets a property key\nhere, winning over a json tag, the legacy swagger:name annotation, and the Go\nfield name.",
  "type": "object",
  "properties": {
    "balance": {
      "description": "Bal has no json tag; the keyword sets the property key directly.",
      "type": "number",
      "format": "double",
      "x-go-name": "Bal"
    },
    "currencyCode": {
      "description": "Currency carries both naming forms; the keyword wins over the\nlegacy annotation and the json tag.",
      "type": "string",
      "x-go-name": "Currency"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

swagger:ignore

swagger:ignore drops a declaration from the output. The scanner sees Secret, classifies it, then excludes it — so it never reaches the definitions (a fact the example’s TestIgnoreOmitsType asserts). It also works on a single struct field — placed on the field’s doc comment, it drops just that property from the model.

// Secret never reaches the spec.
//
// swagger:ignore
type Secret struct {
	// Token is internal.
	Token string `json:"token"`
}

Full source: docs/examples/concepts/models/models.go

Decorating a $ref

When a field’s type resolves to a named model, the property is a $ref — and a bare $ref cannot carry sibling keywords (a JSON Schema draft-4 rule). So a field that is both a reference and decorated (a description, a vendor extension, a default/example, a validation override) would lose its decorations.

codescan avoids that by wrapping the $ref as a member of an allOf. The property is then an ordinary schema object, free to carry the decorations alongside the reference:

• the description and any x-* extensions sit on the property itself;
• a value override (default, example) rides a second allOf member;
• required rides the parent model’s required list.

// 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 that also carries a description and
// a vendor extension. A bare $ref cannot hold sibling keywords, so codescan
// wraps the reference as a member of an allOf — the property is then a normal
// schema that keeps the description and the x-* extension, and required goes to
// the parent. Nothing is dropped.
//
// swagger:model
type Person struct {
	// Home is where the person lives.
	//
	// required: true
	// extensions:
	//   x-ui-order: 3
	Home Address `json:"home"`
}

{
  "description": "Person references Address through a field that also carries a description and\na vendor extension. A bare $ref cannot hold sibling keywords, so codescan\nwraps the reference as a member of an allOf — the property is then a normal\nschema that keeps the description and the x-* extension, and required goes to\nthe parent. Nothing is dropped.",
  "type": "object",
  "required": [
    "home"
  ],
  "properties": {
    "home": {
      "description": "Home is where the person lives.",
      "allOf": [
        {
          "$ref": "#/definitions/Address"
        }
      ],
      "x-go-name": "Home",
      "x-ui-order": 3
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/refoverride"
}

Nothing is dropped. The description-only case is the exception — it is governed by the DescWithRef option (see Descriptions beside a $ref) — and a default/example on a $ref’d field is shown in Examples & defaults.

What’s next

• Routes & operations — wire these models into paths, parameters and responses.
• Validations — constrain field values with keyword annotations.
• Shaping the output — alias handling, $ref vs inline, nullable pointers and more.

Enumerations

An enum in Go is a named type plus a block of constants. swagger:enum turns that pair into an enum array on every schema, parameter and header the type reaches. This page covers what the scanner accepts on the value side, what decides the emitted type / format, and the two shapes that do not work.

// swagger:enum Kind        ← annotation: members are collected from the consts
type Kind string
const (
	KindA Kind = "a"
	KindB Kind = "b"
)

type Filter struct {
	// enum: asc, desc       ← keyword: members are taken verbatim
	Order string `json:"order"`
}

Every Go snippet below comes from the test-covered docs/examples/concepts/enums package, and every JSON pane is a golden file a test regenerates.

swagger:enum

swagger:enum <name> collects the const values declared with that type. A bare swagger:enum on the type declaration works too — the name is inferred from the declaration it sits on.

The enum type is emitted because something points at it: a model field, a parameter, a header. On its own it is unreachable, and unreachable types are not published. Add swagger:model to the enum type to make it a first-class definition (carrying the enum array) that fields $ref instead — the general swagger:model ⇒ definition + $ref rule.

Each member’s doc comment becomes a line of the x-go-enum-desc extension, and is appended to the property description. Set SkipEnumDescriptions to keep the mapping on the extension only.

Any constant expression, not just literals

The values come from the Go type-checker, which has already evaluated the const block. So the members do not have to be written as literals — anything the compiler can fold is collected.

iota is the case that matters most, because after the first line there is nothing left in the source to read: the following specs carry neither a type nor a value, and inherit both implicitly.

// Weekday is an iota enum: only the first spec carries a type and a value, and
// every following one inherits both implicitly.
//
// swagger:enum Weekday
type Weekday int

const (
	// Sunday is the first day.
	Sunday Weekday = iota
	// Monday is the second day.
	Monday
	// Tuesday is the third day.
	Tuesday
)

// Schedule carries the enum, which is what makes it reachable and so emitted.
//
// swagger:model
type Schedule struct {
	// Day the job runs on.
	Day Weekday `json:"day"`
}

{
  "type": "object",
  "title": "Schedule carries the enum, which is what makes it reachable and so emitted.",
  "properties": {
    "day": {
      "description": "Day the job runs on.\n0 Sunday is the first day.\n1 Monday is the second day.\n2 Tuesday is the third day.",
      "type": "integer",
      "format": "int64",
      "enum": [
        0,
        1,
        2
      ],
      "x-go-enum-desc": "0 Sunday is the first day.\n1 Monday is the second day.\n2 Tuesday is the third day.",
      "x-go-name": "Day"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

Constant expressions and references to earlier members are collected the same way.

// Level is built from a constant expression and from a reference to an earlier
// member — neither of which is a literal.
//
// swagger:enum Level
type Level int

const (
	// LevelLow is the floor.
	LevelLow Level = 1 << 3
	// LevelHigh doubles it.
	LevelHigh Level = LevelLow * 2
)

// Threshold carries the computed enum.
//
// swagger:model
type Threshold struct {
	// Level to alert at.
	Level Level `json:"level"`
}

{
  "type": "object",
  "title": "Threshold carries the computed enum.",
  "properties": {
    "level": {
      "description": "Level to alert at.\n8 LevelLow is the floor.\n16 LevelHigh doubles it.",
      "type": "integer",
      "format": "int64",
      "enum": [
        8,
        16
      ],
      "x-go-enum-desc": "8 LevelLow is the floor.\n16 LevelHigh doubles it.",
      "x-go-name": "Level"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

The same goes for every other constant form Go offers: negative values, the non-decimal bases (0x2a, 0b101010, 0o52) and digit separators, values above MaxInt64 in an unsigned enum, true / false, rune literals, and both the raw and the escaped string forms.

Negative members are worth a pane of their own, since a signed constant is not a literal in the Go grammar — it is an expression wrapping one:

// PanDirection straddles zero. A signed constant is not a literal in the Go
// grammar — it is an expression wrapping one — so these are the members that
// used to go missing.
//
// swagger:enum PanDirection
type PanDirection int8

const (
	// PanLeft pans to the left.
	PanLeft PanDirection = -1
	// NoPan holds the current position.
	NoPan PanDirection = 0
	// PanRight pans to the right.
	PanRight PanDirection = 1
)

// Camera carries the signed enum, declared int8.
//
// swagger:model
type Camera struct {
	// Pan direction of the camera.
	Pan PanDirection `json:"pan"`
}

{
  "type": "object",
  "title": "Camera carries the signed enum, declared int8.",
  "properties": {
    "pan": {
      "description": "Pan direction of the camera.\n-1 PanLeft pans to the left.\n0 NoPan holds the current position.\n1 PanRight pans to the right.",
      "type": "integer",
      "format": "int8",
      "enum": [
        -1,
        0,
        1
      ],
      "x-go-enum-desc": "-1 PanLeft pans to the left.\n0 NoPan holds the current position.\n1 PanRight pans to the right.",
      "x-go-name": "Pan"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

The type comes from the declaration

type and format are read from the Go type you declared, never from the members. PanDirection above is an int8, so the property is {integer, int8} — even though every member would fit in a smaller or larger box.

This is also what makes the const block safe to reorder. Zoom is a float32 whose first member is written 0, an integer literal; the schema is a number enum regardless of which member comes first:

// Zoom is a float32 enum whose FIRST member is written as an integer literal.
// The schema type follows the declared type, so the block can be reordered
// freely.
//
// swagger:enum Zoom
type Zoom float32

const (
	// ZoomNone is the neutral step.
	ZoomNone Zoom = 0
	// ZoomOut steps back.
	ZoomOut Zoom = -1.5
	// ZoomIn steps in.
	ZoomIn Zoom = 1.5
)

// Lens carries the float enum.
//
// swagger:model
type Lens struct {
	// Zoom step of the lens.
	Zoom Zoom `json:"zoom"`
}

{
  "type": "object",
  "title": "Lens carries the float enum.",
  "properties": {
    "zoom": {
      "description": "Zoom step of the lens.\n0 ZoomNone is the neutral step.\n-1.5 ZoomOut steps back.\n1.5 ZoomIn steps in.",
      "type": "number",
      "format": "float",
      "enum": [
        0,
        -1.5,
        1.5
      ],
      "x-go-enum-desc": "0 ZoomNone is the neutral step.\n-1.5 ZoomOut steps back.\n1.5 ZoomIn steps in.",
      "x-go-name": "Zoom"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

A type declared over another named type keeps what that type contributed. An enum written over a string format is still that format:

// Kind is an enum written over a string format rather than over a plain string:
// the format of the type it is declared over comes with it.
//
// swagger:enum Kind
type Kind strfmt.UUID

const (
	// KindPrimary is the primary kind.
	KindPrimary Kind = "0a8bcf1e-0000-0000-0000-000000000000"
	// KindSecondary is the secondary kind.
	KindSecondary Kind = "0a8bcf1e-1111-1111-1111-111111111111"
)

// Label carries the formatted enum.
//
// swagger:model
type Label struct {
	// Kind of the label.
	Kind Kind `json:"kind"`
}

{
  "type": "object",
  "title": "Label carries the formatted enum.",
  "properties": {
    "kind": {
      "description": "Kind of the label.\n0a8bcf1e-0000-0000-0000-000000000000 KindPrimary is the primary kind.\n0a8bcf1e-1111-1111-1111-111111111111 KindSecondary is the secondary kind.",
      "type": "string",
      "format": "uuid",
      "enum": [
        "0a8bcf1e-0000-0000-0000-000000000000",
        "0a8bcf1e-1111-1111-1111-111111111111"
      ],
      "x-go-enum-desc": "0a8bcf1e-0000-0000-0000-000000000000 KindPrimary is the primary kind.\n0a8bcf1e-1111-1111-1111-111111111111 KindSecondary is the secondary kind.",
      "x-go-name": "Kind"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

Parameters and headers

OpenAPI 2.0 forbids a $ref on a non-body parameter or a response header, so there the members and the format are written inline. Nothing changes on the annotation side — the same enum type reaches in: query, path, header and formData, and the items of an array-typed one:

// SearchParams consumes an enum from a non-body parameter, where OpenAPI 2.0
// forbids a $ref: the members and the format ship inline.
//
// swagger:parameters search
type SearchParams struct {
	// Direction to pan while searching.
	//
	// in: query
	Pan PanDirection `json:"pan"`

	// Directions the client accepts.
	//
	// in: query
	Accepted []PanDirection `json:"accepted"`
}

[
  {
    "enum": [
      -1,
      0,
      1
    ],
    "type": "integer",
    "format": "int8",
    "x-go-enum-desc": "-1 PanLeft pans to the left.\n0 NoPan holds the current position.\n1 PanRight pans to the right.",
    "x-go-name": "Pan",
    "description": "Direction to pan while searching.\n-1 PanLeft pans to the left.\n0 NoPan holds the current position.\n1 PanRight pans to the right.",
    "name": "pan",
    "in": "query"
  },
  {
    "type": "array",
    "items": {
      "enum": [
        -1,
        0,
        1
      ],
      "type": "integer",
      "format": "int8"
    },
    "x-go-name": "Accepted",
    "description": "Directions the client accepts.",
    "name": "accepted",
    "in": "query"
  }
]

Two shapes that do not work

A rune or byte enum emits integers. It is collected like any other, and 'a' reaches the spec as 97:

// Letter is a rune enum. A rune is an int32, on the wire as much as in Go, so
// the members are code points — 'a' is 97.
//
// swagger:enum Letter
type Letter rune

const (
	// LetterA is the first letter.
	LetterA Letter = 'a'
	// LetterB is the second letter.
	LetterB Letter = 'b'
)

// Glyph carries the rune enum.
//
// swagger:model
type Glyph struct {
	// Letter of the glyph.
	Letter Letter `json:"letter"`
}

{
  "type": "object",
  "title": "Glyph carries the rune enum.",
  "properties": {
    "letter": {
      "description": "Letter of the glyph.\n97 LetterA is the first letter.\n98 LetterB is the second letter.",
      "type": "integer",
      "format": "int32",
      "enum": [
        97,
        98
      ],
      "x-go-enum-desc": "97 LetterA is the first letter.\n98 LetterB is the second letter.",
      "x-go-name": "Letter"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

That is unlikely to be what you pictured, and it is the only faithful answer: a scalar rune is an int32 on the wire as much as in Go, so json.Marshal writes 97, and encoding/json refuses to unmarshal "a" back into the field. A string-typed schema would describe a payload your own server rejects. If you meant characters, declare the type over string (type Letter string, LetterA Letter = "a") — that changes the wire, and the schema follows.

An alias to a basic type cannot host an enum.

type Unsigned = uint64          // an alias, not a new type

// swagger:enum Unsigned        // ← collects nothing
const Zero Unsigned = 0

The Go type-checker erases the alias, so Zero is indistinguishable from any other uint64 constant and there is no set of members to collect. Declare a real type instead (type Unsigned uint64). An alias to a named enum type is fine — the named type survives.

Where to go next

• Validations — the other constraints a property can carry, and the reduced surface parameters accept.
• Model definitions — the rest of the per-type annotations.
• swagger:enum reference — the exhaustive rule.

Maps & free-form objects

Not every object has a fixed set of named fields. A Go map models an object with dynamic keys; a struct can be marked open (extra keys allowed), closed (extra keys forbidden), or given a typed value schema for its extras. codescan expresses all of this with additionalProperties and patternProperties. The panes below are rendered from the test-covered docs/examples/concepts/maps package.

Maps become objects

A map field renders as {type: object} whose values all share one schema, carried as additionalProperties — the value schema is derived from the Go map’s element type:

// Inventory shows a plain Go map. A map renders as an object whose values all
// share one schema, carried as additionalProperties.
//
// swagger:model
type Inventory struct {
	// Counts maps each SKU to its on-hand quantity.
	Counts map[string]int `json:"counts"`
}

{
  "description": "Inventory shows a plain Go map. A map renders as an object whose values all\nshare one schema, carried as additionalProperties.",
  "type": "object",
  "properties": {
    "counts": {
      "description": "Counts maps each SKU to its on-hand quantity.",
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "format": "int64"
      },
      "x-go-name": "Counts"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

Which map keys work

A map key has to become a JSON object key — a string. codescan accepts every key type encoding/json can stringify: string kinds, every integer / unsigned kind (so map[int]V, map[uint8]V, …), and any type implementing encoding.TextMarshaler. An integer-keyed map is therefore still a valid object:

// Lookups shows which Go map keys survive. A key is usable when encoding/json
// can stringify it: string kinds, every integer/unsigned kind, and types
// implementing encoding.TextMarshaler. Other keys (float, bool, struct without
// TextMarshaler) are dropped with a diagnostic.
//
// swagger:model
type Lookups struct {
	// ByName is keyed by a plain string.
	ByName map[string]int `json:"byName"`

	// ByCode is keyed by an integer — JSON stringifies it, so the map is still
	// an object with additionalProperties.
	ByCode map[int]string `json:"byCode"`
}

{
  "description": "Lookups shows which Go map keys survive. A key is usable when encoding/json\ncan stringify it: string kinds, every integer/unsigned kind, and types\nimplementing encoding.TextMarshaler. Other keys (float, bool, struct without\nTextMarshaler) are dropped with a diagnostic.",
  "type": "object",
  "properties": {
    "byCode": {
      "description": "ByCode is keyed by an integer — JSON stringifies it, so the map is still\nan object with additionalProperties.",
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "x-go-name": "ByCode"
    },
    "byName": {
      "description": "ByName is keyed by a plain string.",
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "format": "int64"
      },
      "x-go-name": "ByName"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

Open & closed objects

A struct normally renders with just its named properties and says nothing about extra keys. The decl-level swagger:additionalProperties <spec> marker decides the policy, where <spec> is true, false, or a value type:

// ClosedObject forbids any key beyond its named properties: the marker false
// closes the object.
//
// swagger:model
// swagger:additionalProperties false
type ClosedObject struct {
	A string `json:"a"`
	B int    `json:"b"`
}

// OpenObject keeps its named property and also allows arbitrary extra keys.
//
// swagger:model
// swagger:additionalProperties true
type OpenObject struct {
	A string `json:"a"`
}

// TypedObject complements its named property with typed (integer) extra values.
//
// swagger:model
// swagger:additionalProperties integer
type TypedObject struct {
	A string `json:"a"`
}

// RefObject references a model as the schema of its extra values.
//
// swagger:model
// swagger:additionalProperties Thing
type RefObject struct {
	A string `json:"a"`
}

Full source: docs/examples/concepts/maps/maps.go

false closes the object (only the named properties are valid); true opens it (any extra key is allowed):

{
  "description": "ClosedObject forbids any key beyond its named properties: the marker false\ncloses the object.",
  "type": "object",
  "properties": {
    "a": {
      "type": "string",
      "x-go-name": "A"
    },
    "b": {
      "type": "integer",
      "format": "int64",
      "x-go-name": "B"
    }
  },
  "additionalProperties": false,
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

{
  "type": "object",
  "title": "OpenObject keeps its named property and also allows arbitrary extra keys.",
  "properties": {
    "a": {
      "type": "string",
      "x-go-name": "A"
    }
  },
  "additionalProperties": true,
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

A type spec instead of a bool gives the extra values a schema — a primitive (or []T), or a model name that becomes a $ref (the same value-type grammar as swagger:type, except a type name resolves to a $ref):

{
  "type": "object",
  "title": "TypedObject complements its named property with typed (integer) extra values.",
  "properties": {
    "a": {
      "type": "string",
      "x-go-name": "A"
    }
  },
  "additionalProperties": {
    "type": "integer"
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

{
  "type": "object",
  "title": "RefObject references a model as the schema of its extra values.",
  "properties": {
    "a": {
      "type": "string",
      "x-go-name": "A"
    }
  },
  "additionalProperties": {
    "$ref": "#/definitions/Thing"
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

On a map type the marker overrides the element-derived value schema; on a struct it complements the named properties (as above). It composes with the object validations maxProperties / minProperties / patternProperties.

Per-field control

The same <spec> is available as a field keyword, additionalProperties: <spec>, decorating one struct field. On a map field it overrides the value schema; on a $ref’d field the value rides an allOf sibling so the reference is preserved:

// Holder decorates individual fields with the additionalProperties: keyword.
//
// swagger:model
type Holder struct {
	// OverriddenMap keeps its map shape but overrides the value schema from the
	// Go element type (string) to integer.
	//
	// additionalProperties: integer
	OverriddenMap map[string]string `json:"overriddenMap"`

	// RefMap points the map values at a model.
	//
	// additionalProperties: Thing
	RefMap map[string]string `json:"refMap"`

	// ClosedRef references a model and forbids extra keys. Because the field is
	// a $ref, the value rides an allOf sibling so the reference is preserved.
	//
	// additionalProperties: false
	ClosedRef Thing `json:"closedRef"`
}

{
  "type": "object",
  "title": "Holder decorates individual fields with the additionalProperties: keyword.",
  "properties": {
    "closedRef": {
      "description": "ClosedRef references a model and forbids extra keys. Because the field is\na $ref, the value rides an allOf sibling so the reference is preserved.",
      "allOf": [
        {
          "$ref": "#/definitions/Thing"
        },
        {
          "additionalProperties": false
        }
      ],
      "x-go-name": "ClosedRef"
    },
    "overriddenMap": {
      "description": "OverriddenMap keeps its map shape but overrides the value schema from the\nGo element type (string) to integer.",
      "type": "object",
      "additionalProperties": {
        "type": "integer"
      },
      "x-go-name": "OverriddenMap"
    },
    "refMap": {
      "description": "RefMap points the map values at a model.",
      "type": "object",
      "additionalProperties": {
        "$ref": "#/definitions/Thing"
      },
      "x-go-name": "RefMap"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

Pattern properties

patternProperties constrains extra keys by a name regex rather than allowing all of them. The regex-only patternProperties: keyword maps a pattern to an empty (any-value) schema. The decl-level swagger:patternProperties "<re>": <spec>, … marker is the typed counterpart — each quoted regex pairs with a value spec (a primitive, or a model name that becomes a $ref):

// TypedPatterns maps property-name regexes to typed value schemas. Each quoted
// regex pairs with a value spec — a primitive or a model name (which becomes a
// $ref). The pattern-properties keyword is JSON-Schema, beyond the Swagger 2.0
// subset; codescan emits it ungated.
//
// swagger:model
// swagger:patternProperties "^x-": string, "^\d+$": integer, "^item-": Thing
type TypedPatterns struct {
	Known string `json:"known"`
}

{
  "description": "TypedPatterns maps property-name regexes to typed value schemas. Each quoted\nregex pairs with a value spec — a primitive or a model name (which becomes a\n$ref). The pattern-properties keyword is JSON-Schema, beyond the Swagger 2.0\nsubset; codescan emits it ungated.",
  "type": "object",
  "properties": {
    "known": {
      "type": "string",
      "x-go-name": "Known"
    }
  },
  "patternProperties": {
    "^\\d+$": {
      "type": "integer"
    },
    "^item-": {
      "$ref": "#/definitions/Thing"
    },
    "^x-": {
      "type": "string"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}