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
- 2025-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
import (
"github.com/go-openapi/codescan"
)
swaggerSpec, err := codescan.Run(&codescan.Options{
Packages: []string{"./..."},
})
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 |
|---|---|
|
internal
|
|
|
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/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. |
|
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. |
|
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. |