📖 3 min read (~ 500 words).

go-openapi codescan

github.com/go-openapi/codescan is a Go source code scanner that produces Swagger 2.0 (OpenAPI 2.0) specifications.

It reads specially formatted comments (annotations) in Go source files and extracts API metadata — routes, parameters, responses, schemas and more — to build a complete spec.Swagger document. It supports Go modules (since go1.11).

The scanner works entirely at the AST / go/types level: it never compiles or executes the code it scans. It only reads the source and its annotation comments.

Status

Fork me Stable API. Actively maintained.

The only exposed API is Run() and Options.

Getting started

go get github.com/go-openapi/codescan

Point the scanner at one or more packages and get back a *spec.Swagger:

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

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

Where to go next

  • About

    What codescan is, why scan source to a spec, and how it relates to go-swagger.

    → about

  • Getting started

    Install the scanner, annotate a package, and produce your first spec.

    → getting-started

  • Tutorials

    Learn by spec concept — model definitions, routes, validations — annotated Go next to the spec it produces.

    → tutorials

  • Shaping the output

    How-to guides for the rendering knobs: $ref vs inline, aliases, nullable pointers, extensions.

    → shaping-the-output

  • Annotation index

    Every annotation at a glance, linked to its worked example and its full reference.

    → annotation-index

  • Reference (maintainers)

    The complete compendium — annotations, keywords, sub-languages and the formal grammar.

    → maintainers

  • Project

    Repo overview, license and links to the shared go-openapi guides.

    → project

Licensing

SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers

This library ships under the Apache-2.0 license.

Contributing

Issues and pull requests welcome.

See the shared go-openapi contributing guidelines and the per-repo notes in project/.

  • Repo-level information for github.com/go-openapi/codescan. Cross-org contributing and maintainer guides live in the shared go-openapi doc-site.
  • What codescan is, why you would scan source to produce a spec, and how it relates to the go-swagger toolkit.
  • Install codescan and choose how to drive it. Today the scanner is consumed as a Go library; more usage modes will be added here as siblings.
  • Learn codescan by spec concept — model definitions, routes and operations, validations, examples, and document metadata — each shown as annotated Go next to the Swagger it produces.
  • How-to guides for the knobs that change how the same Go source renders into the spec — $ref vs inline, alias handling, descriptions beside a $ref, nullable pointers, vendor extensions, and spec overlays.
  • Every swagger:* annotation at a glance — what it produces and where it attaches — linked to both its worked example and its full reference.
  • The complete, normative reference for the codescan annotation language — every annotation, every keyword, the embedded sub-languages, and the formal grammar the parser implements.