go-bricks-openapi

go-bricks-openapi

Static-analysis–based OpenAPI 3.0.1 specification generator for GoBricks services.

It discovers your modules, routes, and typed request/response models by parsing your source with go/ast — it never imports or runs your service, so spec generation is fast, hermetic, and needs no build of the target project.

Installation

# Install the latest release with the Go toolchain
go install github.com/gaborage/go-bricks-openapi/cmd/go-bricks-openapi@latest

Prebuilt binaries for Linux, macOS, and Windows are attached to each GitHub Release.

Verifying a release

Every release artifact carries a signed SLSA build provenance attestation generated by GitHub. Download an archive from the releases page, then verify it against this repository before trusting it:

gh attestation verify go-bricks-openapi_0.1.0_darwin_arm64.tar.gz \
  --repo gaborage/go-bricks-openapi

Or build from source:

git clone https://github.com/gaborage/go-bricks-openapi.git
cd go-bricks-openapi
make install   # builds and installs go-bricks-openapi into $GOBIN

Usage

# Generate an OpenAPI spec from a GoBricks service
go-bricks-openapi generate --project . --output docs/openapi.yaml

# Check environment & project compatibility before generating
go-bricks-openapi doctor --project .

# Validate an existing OpenAPI 3.0 document (YAML or JSON), no network needed
go-bricks-openapi validate docs/openapi.yaml

# Print version / build info
go-bricks-openapi version

Commands

generate flags

Marking a route as public

By default every operation carries the tenant security scheme. A route that needs no auth (health checks, login, webhooks) can opt out with an //openapi:public comment directive on the line directly above its registration call:

func (m *Module) RegisterRoutes(hr *server.HandlerRegistry, r server.RouteRegistrar) {
	//openapi:public
	server.GET(hr, r, "/ping", ping, server.WithTags("health"))
}

The generator emits security: [] for that operation. go-bricks itself has no per-route tenant opt-out API as of v0.53.0, so this directive is the tool's own annotation — it has no runtime effect.

Requirements

• Go 1.25+ to build/run the tool. (Target projects on GoBricks v0.45.0+ require Go 1.26+ to build themselves, but the tool only parses their source, so it doesn't inherit that requirement.)
• Targets GoBricks v0.45.0+ projects — v0.45.0 is the release that hid the echo dependency behind go-bricks boundary types — verified through v0.53.0. doctor fails below the floor; generate warns and fails only under --strict.

Known limitations

• Raw/untyped routes (r.Add, RegisterReadyHandler) are discovered but have no request/response schema — they show up as untyped in doctor diagnostics.
• Routes registered outside a module's RegisterRoutes (e.g. via RootGroup() in main) are not discovered.
• Embedded-module method promotion is not resolved.
• Response trace headers (traceparent, X-Request-ID) are not modeled in the generated spec.
• server.WithMiddleware(...) is intentionally ignored — middleware names carry no spec semantics.
• Tenant enforcement is not derived from runtime config; the security scheme reflects static analysis of route registration only.

Development

Run make dev-deps once to install the pinned golangci-lint; make check needs it, and make validate-spec additionally needs npx.

make check          # fmt + lint + test (race) + validate-cli — the pre-commit gate
make test           # unit tests with race detection
make test-coverage  # coverage profile + HTML report
make validate-cli   # build the binary and smoke-test version/doctor/generate
make validate-spec  # generate a fixture spec and lint it with redocly (needs npx)

The test suite is hermetic: the internal/spectest harness runs the real analyze → generate → validate pipeline over the fixture projects under internal/spectest/testdata/ and validates the emitted documents in-process against OpenAPI 3.0 (no network required).

Releasing

Versioning and the release process (a release-please standing PR plus a locally-cut signed tag) are documented in RELEASING.md.

License

Apache 2.0