Usage as a library

The most direct way to use codescan from your own Go program is to import it and call Run.

This supports various use-cases such as a generator, a go:generate step, or a test that keeps your spec in sync with the source.

Install

go get github.com/go-openapi/codescan

codescan exposes a deliberately small surface: a single Run function and an Options struct.

func Run(opts *Options) (*spec.Swagger, error)

Annotate your source

Annotations are special comments following the go-swagger convention (swagger:meta, swagger:route, swagger:model, swagger:parameters, swagger:response, …).

A package-level swagger:meta block carries the top-level metadata of the spec:

// Package petstore Petstore API
//
// A tiny pet store, used to demonstrate codescan annotations: the package
// comment is a `swagger:meta` block carrying the top-level metadata of the
// generated specification (title, description, version, base path, …).
//
//	Schemes: https
//	Version: 1.0.0
//	BasePath: /v1
//
//	Consumes:
//	- application/json
//
//	Produces:
//	- application/json
//
// swagger:meta

Full source: docs/examples/petstore/doc.go

A swagger:model annotation turns a Go struct into a definition; field-level comments become validations and descriptions:

// Pet is a single pet in the store.
//
// swagger:model Pet
type Pet struct {
	// The id of the pet.
	//
	// required: true
	// minimum: 1
	ID int64 `json:"id"`

	// The name of the pet.
	//
	// required: true
	// min length: 1
	Name string `json:"name"`

	// The tags associated with this pet.
	Tags []string `json:"tags,omitempty"`
}

Full source: docs/examples/petstore/pet.go

Run the scanner

Point codescan at the package(s) to scan. Patterns are relative go list-style patterns, resolved against WorkDir:

opts := &codescan.Options{
	WorkDir:    workDir,                // module root to resolve patterns from
	Packages:   []string{"./petstore"}, // relative package pattern
	ScanModels: true,                   // also emit definitions for swagger:model types
}

doc, err := codescan.Run(opts)
if err != nil {
	return nil, err
}

Full source: docs/examples/basic/scan.go

The returned *spec.Swagger is the standard github.com/go-openapi/spec document — marshal it to JSON or YAML, feed it to a validator, or merge it onto an existing spec via Options.InputSpec.

Options worth knowing

Those are the ones a first call tends to need. Everything else — alias handling, $ref siblings, naming, doc-comment cleanup, the loader, the go environment — is in the Options reference, which gives each field with its command-line and configuration-file spellings beside it. The godoc is the normative source.

Dependencies

Code loading relies by default on the go toolchain and this requires go to be installed.

To alleviate this constraint, you may want to use the pure-go ToolchainFreeLoader loader in your options, so programs that build on top of codescan don’t shell out a go list command.

Next

• Scan a package — the whole of the above as one runnable, test-covered example.
• Usage as a headless CLI — the same scan without writing a program, for a build or a pipeline.
• Tutorials — the worked, by-concept version of the above, each with the spec it produces.
• Annotation index — every annotation at a glance, linked to its example and its full reference.
• Maintainers reference — the complete annotation vocabulary, keywords, and grammar.