Regenerating

This is the command reference for regenerating go-unifi's generated code. For what the pipeline does, read Code generation first. A local-only Makefile wraps every command below.

Regenerate everything (canonical)

The one command CI runs — it regenerates both surfaces (Internal resources + the Official models, wrappers, interface, and mock) from the committed snapshots, offline:

go generate unifi/codegen.go

This invokes the directive in unifi/codegen.go, which pins both version axes explicitly (-legacy-version=9.5.21 10.1.85 — the positional argument is the Official spec version), so the result is byte-for-byte reproducible. After running it, git diff should be empty unless a snapshot, template, or customizations.yml actually changed.

Regenerate the DeviceState stringer

DeviceState has a generated String() method. Regenerate it after changing the enum:

go generate unifi/device.go

CI's stringer job runs this and fails on any diff.

The Makefile wrappers

make generate              # stringer + resources
make generate-stringer     # just the DeviceState stringer
make generate-resources    # just the resource types (VERSION=latest by default)

make generate-resources runs the root generator directly, passing VERSION as the positional Official-spec-version argument:

go run ./codegen/ -version-base-dir=./codegen/ -output-dir=./unifi <VERSION>

VERSION pins the Official spec version (default latest); override the Internal controller version with -legacy-version (default latest, which clamps to the 9.5.21 cap):

make generate-resources VERSION=10.1.85
make generate VERSION=10.1.85     # stringer + resources at that spec version

Regenerate the moq mock

ClientMock (in unifi/client_mock.generated.go) is a moq-generated double for the public Client interface. Regenerate it after changing the interface:

go generate ./unifi/...
# equivalently:
go run github.com/matryer/moq@latest -out client_mock.generated.go . Client

Pinning the Official spec version

The Official OpenAPI spec version is the positional argument; -legacy-version pins the Internal version independently:

go run ./codegen/ -version-base-dir=./codegen/ -output-dir=./unifi \
  -legacy-version=9.5.21 10.1.85

Multiple snapshots may be committed side by side under codegen/openapi/ — the positional version selects which one the Go surface is generated from. When the snapshot codegen/openapi/integration-<ver>.json is already committed, the generator uses it offline; otherwise it downloads and commits it (keeping any existing snapshots). The docs website always renders the newest committed snapshot.

Refreshing a frozen snapshot

The Internal field inputs are frozen at codegen/v9.5.21/ (a committed snapshot plus a .gitignore un-ignore rule), which is why daily regeneration is a deterministic no-op. To move to a new Internal snapshot:

Refreshing the Official spec is simpler: bump the positional version in the unifi/codegen.go directive (the older integration-<ver>.json can stay committed alongside the new one), regenerate to download and commit the new snapshot, and verify the diff.

Verify before committing

go build ./...
go generate unifi/codegen.go && git diff --exit-code   # mirrors CI's test-codegen
make check                                              # build + lint + test

See also