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-wasi is the headless counterpart: it writes the specification to standard output and takes no dependency beyond the library, so it also cross-compiles to WebAssembly and runs under a WASI runtime with no Go toolchain installed.

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

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

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