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
-
2026-07-31 : landed a new spec generation TUI tool
-
2026-04-19 : large package layout reshuffle
- the entire project is being refactored to restore a reasonable level of maintenability
- 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 as a library
import (
"github.com/go-openapi/codescan"
)
swaggerSpec, err := codescan.Run(&codescan.Options{
Packages: []string{"./..."},
})
Work with the TUI
This project comes with a terminal UI to quickly render a Swagger spec from source and navigate your code annotations. It shows diagnostics and you may test the impact of the various available options.
go install github.com/go-openapi/codescan/cmd/genspec-tui@latest
genspec-tui -workdir [my source location]
A walkthrough of what it is for — scanning, tracking a node back to its source, diagnostics and spec validation — is on the doc site: Usage as a terminal UI.
Generate a spec from the command line
genspec is the headless counterpart: it writes the specification to standard output, or to the file
-output names, and reports what the scan observed as colored diagnostics on standard error.
go install github.com/go-openapi/codescan/cmd/genspec@latest
genspec -workdir [my source location] ./...
Every option the library takes is a flag. Beyond those, it writes YAML as readily as JSON
(-output swagger.yaml is enough), merges its discoveries into an existing document with -input,
and checks what it produced with -validate. Its exit status says which of those went wrong.
It does the same job as go-swagger's swagger generate spec, which drives this same library, but is
released on its own — so fixes and enhancements reach it at this project's pace, and it carries only
the dependencies a spec generator needs.
Where there is no Go toolchain
genspec-wasi runs the same scan taking no dependency beyond the library, so it cross-compiles to
WebAssembly and runs under a WASI runtime with no Go toolchain installed and no subprocess.
go install github.com/go-openapi/codescan/cmd/genspec-wasi@latest
genspec-wasi -workdir [my source location] ./...
-format=json wraps the document with everything the scan observed — diagnostics
and cross-references, each carrying a source position — for a caller that wants
to do something with them rather than read them.
See cmd/genspec-wasi/README.md for the WASI build, what a guest needs mounted, and how to ship the standard library's types inside the artifact.
Scan in a browser
Experimental, and offered for demonstration — the interface is verified by hand rather than by
tests. hack/doc-site/genspec-wasi is the same
artifact with a front-end around it: open a Go module, watch the specification it produces, edit the
source and watch it change. There is no server and nothing is uploaded — the scanner is codescan
compiled to WebAssembly, running in the tab.
It follows genspec-tui closely enough to be judged against it: syntax highlighting on both sides, a
diagnostics gutter, / search, and cross-references that answer which Go code produced this node
and what did this field turn into — by position rather than by guessing at names.
Destined for the documentation site, where a tutorial's example box becomes something you can edit.
Change log
See https://github.com/go-openapi/codescan/releases
Licensing
This library ships under the SPDX-License-Identifier: Apache-2.0.
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
Cutting a new release
Maintainers can cut a new release by either:
- running this workflow
- or pushing a semver tag
- signed tags are preferred
- The tag message is prepended to release notes
Documentation
¶
Overview ¶
Package codescan provides a scanner for go files that produces a swagger spec document.
This package is intended for go1.25 onwards and uses go1.26 toolchain.
It supports go modules.
Index ¶
Constants ¶
const ( SeverityError = grammar.SeverityError SeverityWarning = grammar.SeverityWarning SeverityHint = grammar.SeverityHint )
Severity levels, ordered from most to least serious.
const (
// ErrCodeScan is the sentinel error for all errors originating from the codescan package.
ErrCodeScan codescanError = "codescan error"
)
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Code ¶ added in v0.35.0
Code is a stable, machine-readable identifier for a class of Diagnostic (e.g. "validate.unsupported-go-type", "scan.ignored-by-tag").
Codes are grouped by prefix: parse.* (lexer/parser), validate.* (semantic), scan.* (scan environment). Callers may switch on it to filter or route diagnostics.
type Diagnostic ¶ added in v0.35.0
type Diagnostic = grammar.Diagnostic
Diagnostic is one observation the scanner makes about the source it processes — a parse/validation issue, a dropped construct, or an informational note.
Every scan-time observation is delivered to [Options.OnDiagnostic]; codescan never writes to stdout/stderr.
Fields: Pos (a go/token.Position, zero when no single source location applies), Severity, Code (a stable machine-readable identifier), and a human-readable Message. The String method renders it in compiler-style one-line form.
type Severity ¶ added in v0.35.0
Severity classifies a Diagnostic's seriousness.
The scan never aborts on a Warning or Hint; the caller decides policy. Compare against SeverityError, SeverityWarning and SeverityHint.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
genspec-wasi
command
Command genspec-wasi scans annotated Go source and writes the Swagger specification it describes.
|
Command genspec-wasi scans annotated Go source and writes the Swagger specification it describes. |
|
internal/cliconf
Package cliconf supplements a command line with a configuration file.
|
Package cliconf supplements a command line with a configuration file. |
|
internal/cliopts
Package cliopts declares codescan's option surface once, as flags.
|
Package cliopts declares codescan's option surface once, as flags. |
|
genspec
module
|
|
|
genspec-tui
module
|
|
|
fixtures
module
|
|
|
hack
|
|
|
genexportdata
command
Command genexportdata extracts the compiler's export data for a set of packages into a directory tree keyed by import path.
|
Command genexportdata extracts the compiler's export data for a set of packages into a directory tree keyed by import path. |
|
go-loader
command
Command go-loader keeps codescan's toolchain-free package loader honest against the go command it stands in for.
|
Command go-loader keeps codescan's toolchain-free package loader honest against the go command it stands in for. |
|
internal
|
|
|
benchmarks
Package benchmarks measures what a scan costs, on two generated projects that ship with this repository.
|
Package benchmarks measures what a scan costs, on two generated projects that ship with this repository. |
|
benchmarks/corpus
Package corpus resolves the trees the benchmarks measure.
|
Package corpus resolves the trees the benchmarks measure. |
|
benchmarks/corpus/unpack
command
Command unpack makes the benchmark corpora available on disk and prints where they are, one `name<TAB>directory` line per corpus.
|
Command unpack makes the benchmark corpora available on disk and prints where they are, one `name<TAB>directory` line per corpus. |
|
benchmarks/loader-benchmark
command
Command loader-benchmark measures one codescan scan and reports what it cost.
|
Command loader-benchmark measures one codescan scan and reports what it cost. |
|
builders/common
Package common holds shared per-Builder state every concrete per-decl builder (schema, parameters, responses, routes, operations, spec) embeds.
|
Package common holds shared per-Builder state every concrete per-decl builder (schema, parameters, responses, routes, operations, spec) embeds. |
|
builders/godoclink
Package godoclink rewrites godoc-specific syntax.
|
Package godoclink rewrites godoc-specific syntax. |
|
builders/handlers
Package handlers ships shared grammar Walker callbacks for the SimpleSchema and full-Schema families of OAS v2 dispatchers.
|
Package handlers ships shared grammar Walker callbacks for the SimpleSchema and full-Schema families of OAS v2 dispatchers. |
|
builders/validations
Package validations owns cross-builder validation and coercion concerns shared by the schema, parameters, responses, and items/headers code paths.
|
Package validations owns cross-builder validation and coercion concerns shared by the schema, parameters, responses, and items/headers code paths. |
|
exportdata
Package exportdata optionally carries dependencies' export data inside the binary.
|
Package exportdata optionally carries dependencies' export data inside the binary. |
|
ifaces
Package ifaces defines the internal interfaces that decouple the comment-parsing pipeline from the concrete Swagger spec builders.
|
Package ifaces defines the internal interfaces that decouple the comment-parsing pipeline from the concrete Swagger spec builders. |
|
integration
Package integration provides integration tests.
|
Package integration provides integration tests. |
|
packages
Package packages loads and type-checks the Go packages codescan scans.
|
Package packages loads and type-checks the Go packages codescan scans. |
|
packages/list
Package list answers the question `go list` answers: given a pattern or an import path, which directory holds that package, and what is it called.
|
Package list answers the question `go list` answers: given a pattern or an import path, which directory holds that package, and what is it called. |
|
packages/vfs
Package vfs is the loader's single point of filesystem contact.
|
Package vfs is the loader's single point of filesystem contact. |
|
parsers/grammar
Package grammar is the annotation parser for codescan.
|
Package grammar is the annotation parser for codescan. |
|
parsers/routebody
Package routebody parses the body sub-language of swagger:route / swagger:operation `Parameters:` and `Responses:` raw blocks.
|
Package routebody parses the body sub-language of swagger:route / swagger:operation `Parameters:` and `Responses:` raw blocks. |
|
parsers/security
Package security is the sub-parser for the `Security:` block body that appears under `swagger:meta`, `swagger:route` and `swagger:operation`.
|
Package security is the sub-parser for the `Security:` block body that appears under `swagger:meta`, `swagger:route` and `swagger:operation`. |
|
parsers/yaml
Package yaml is a thin wrapper around go.yaml.in/yaml/v3 for consuming the RawYAML bodies that internal/parsers/grammar/ isolates between `---` fences, plus the typed-extensions service the grammar lexer calls for `extensions:` raw blocks.
|
Package yaml is a thin wrapper around go.yaml.in/yaml/v3 for consuming the RawYAML bodies that internal/parsers/grammar/ isolates between `---` fences, plus the typed-extensions service the grammar lexer calls for `extensions:` raw blocks. |
|
scanner/classify
Package classify provides small classification predicates used by the scanner and by builders to decide whether a given name or comment line belongs to a particular Swagger-annotation family.
|
Package classify provides small classification predicates used by the scanner and by builders to decide whether a given name or comment line belongs to a particular Swagger-annotation family. |
|
scantest
Package scantest exposes utilities for testing the codescan packages.
|
Package scantest exposes utilities for testing the codescan packages. |
|
scantest/mocks
Package mocks contains mock types for all interfaces.
|
Package mocks contains mock types for all interfaces. |
|
testloader
Package testloader carries the one setting that decides which loader a test run uses.
|
Package testloader carries the one setting that decides which loader a test run uses. |