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

To use codescan in your go program:

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{"./..."},
})

Or as a command, to run in a build or a pipeline:

go install github.com/go-openapi/codescan/cmd/genspec@latest

Or as a terminal front-end, to watch a spec take shape as you annotate:

go install github.com/go-openapi/codescan/cmd/genspec-tui@latest

Try it out now from your browser in our Playground.

Relationship to go-swagger

go-swagger is a CLI tool that consumes the codescan library. It works exactly on the same set of annotations.

The main differences with the newer genspec CLI shipped by this project are:

• release cadence (expect slightly less frequent updates on go-swagger, which has more dependencies and constraints)
• package distribution: at this moment, the codescan CLI tools do not ship as distro packages or docker images
• exposed CLI knobs and default settings (defaults need to be backward-compatible for go-swagger users)

genspec and genspec-tui are intended for users who want tools leaner than go-swagger, or who want to experiment with the latest features.

Where to go next

• About

  What codescan is, why you would scan source to produce a spec.

  How does it relate to the go-openapi & go-swagger toolkits.

• Getting started

  Install codescan and choose how to drive it.

  As a Go library from your own program, as a command in a build, or interactively from the terminal UI.

• Playground

  Scan Go source in your browser.

  Edit annotations, watch the specification change, and follow a spec node back to the code that produced it.

• Advanced Usage

  All the knobs codescan takes. What they are, and how they relate.

  There are three spellings: a Go field, a command-line flag, and a key in a configuration file.

• Project

  Repo-level information for github.com/go-openapi/codescan.

  Contributing guidelines & maintainers documentation.

• Tutorials

  Learn codescan by spec concept: model definitions, routes and operations, validations, examples, and document metadata.

  Each demonstrated as annotated Go next to the Swagger it produces.

• Shaping the output

  How-to guides for the knobs that change how the same Go source renders into the spec.

  Grouped by what they shape: scope & discovery, names & $refs, titles & descriptions, field types & formats, and response bodies.

• Annotation index

  Every swagger:* annotation at a glance.

  What it produces and where it attaches — linked to both its worked example and its full reference.

• Maintainers

  The complete, normative reference for the codescan annotation language.

  Every annotation, every keyword, the embedded sub-languages, the formal grammar the parser implements, and how the commands are put together.