Documentation
¶
Overview ¶
Package openapi provides a Go library for generating OpenAPI 3.1 specifications from Go source code using swagger directives.
Quick Start ¶
Generate an OpenAPI spec from your Go code:
spec, err := openapi.Generate(
openapi.WithDir("."),
openapi.WithPattern("./..."),
openapi.WithOutput("openapi.yaml", "yaml"),
)
Directives ¶
The library scans Go source code for the following directives:
- swagger:meta - API metadata (title, version, description)
- swagger:model - Schema definitions
- swagger:route - Operation definitions
- swagger:parameters - Parameter definitions
- swagger:enum - Enum definitions
Caching ¶
The library supports incremental builds through caching. By default, parsed schemas and routes are cached in a .openapi directory. Only files that have changed since the last build are re-parsed.
To disable caching:
spec, err := openapi.Generate( openapi.WithCache(false), )
Index ¶
Constants ¶
This section is empty.
Variables ¶
var WithCache = generator.WithCache
WithCache enables or disables incremental caching.
var WithCleanUnused = generator.WithCleanUnused
WithCleanUnused enables or disables removal of unreferenced schemas.
var WithDir = generator.WithDir
WithDir sets the root directory to scan from.
var WithEnumRefs = generator.WithEnumRefs
WithEnumRefs enables generating enums as $ref references instead of inline.
var WithFlatten = generator.WithFlatten
WithFlatten enables or disables schema flattening (inlining $refs).
var WithIgnorePaths = generator.WithIgnorePaths
WithIgnorePaths sets path patterns to exclude during scanning.
var WithOutput = generator.WithOutput
WithOutput sets the output file path and format ("yaml" or "json").
var WithPattern = generator.WithPattern
WithPattern sets the package pattern to scan (e.g., "./...", "./api/...").
var WithValidation = generator.WithValidation
WithValidation enables or disables spec validation after generation.
Functions ¶
Types ¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cache provides incremental build caching for OpenAPI spec generation.
|
Package cache provides incremental build caching for OpenAPI spec generation. |
|
Package generator provides OpenAPI specification generation from Go source code.
|
Package generator provides OpenAPI specification generation from Go source code. |
|
Package parser provides an extensible parsing system for swagger directives.
|
Package parser provides an extensible parsing system for swagger directives. |
|
tags
Package tags provides built-in parsers for common swagger directives.
|
Package tags provides built-in parsers for common swagger directives. |
|
Package sdkgen generates Go SDK packages from OpenAPI specs and SDK config files.
|
Package sdkgen generates Go SDK packages from OpenAPI specs and SDK config files. |
|
Package swagger provides an HTTP handler to serve Swagger UI with embedded OpenAPI specs.
|
Package swagger provides an HTTP handler to serve Swagger UI with embedded OpenAPI specs. |