Documentation
¶
Overview ¶
Package generator provides OpenAPI specification generation from Go source code.
Index ¶
- func ClearCustomTypes()
- func ClearExternalSchemas()
- func FieldType(t any, handler TypeHandler)
- func GetAllExternalSchemas() map[string]*spec.Schema
- func GetExternalSchema(name string) *spec.Schema
- func LoadConfigFile(dir string) error
- func RegisterSchema(name string, schema *spec.Schema)
- func RegisterType(typeName string, handler TypeHandler)
- func RegisterTypeInfo(typeName string, info *TypeInfo)
- func ResetToDefaults()
- type Config
- type ConfigFile
- type Generator
- type Option
- func WithCache(enabled bool) Option
- func WithCleanUnused(clean bool) Option
- func WithDir(dir string) Option
- func WithEnumRefs(enumRefs bool) Option
- func WithFlatten(flatten bool) Option
- func WithIgnorePaths(paths ...string) Option
- func WithNoDefault(noDefault bool) Option
- func WithOutput(file, format string) Option
- func WithPattern(pattern string) Option
- func WithValidation(validate bool) Option
- type TypeConfig
- type TypeHandler
- type TypeInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClearCustomTypes ¶
func ClearCustomTypes()
ClearCustomTypes removes all registered custom types. Useful for testing.
func ClearExternalSchemas ¶
func ClearExternalSchemas()
ClearExternalSchemas removes all registered external schemas.
func FieldType ¶
func FieldType(t any, handler TypeHandler)
FieldType registers a custom type handler for OpenAPI schema generation. Pass a zero value of the type to register.
Example:
generator.FieldType(decimal.Decimal{}, func(info *generator.TypeInfo) {
info.Type = "string"
info.Format = "decimal"
info.Example = "100.00000000"
})
generator.FieldType(uuid.UUID{}, func(info *generator.TypeInfo) {
info.Type = "string"
info.Format = "uuid"
})
func GetAllExternalSchemas ¶
GetAllExternalSchemas returns a copy of all external schemas.
func GetExternalSchema ¶
GetExternalSchema returns the external schema for the given name.
func LoadConfigFile ¶
LoadConfigFile loads custom types and schemas from .openapi.yaml in the given directory. It searches for .openapi.yaml, .openapi.yml, or openapi.config.yaml.
func RegisterSchema ¶
RegisterSchema registers an external schema by name.
func RegisterType ¶
func RegisterType(typeName string, handler TypeHandler)
RegisterType registers a custom type handler by type name string. Prefer using FieldType with the actual type for type safety.
func RegisterTypeInfo ¶
RegisterTypeInfo registers a TypeInfo directly for a custom type.
func ResetToDefaults ¶
func ResetToDefaults()
ResetToDefaults clears all custom types and re-registers the defaults. Useful for testing.
Types ¶
type Config ¶
type Config struct {
// Dir is the root directory of the project
Dir string
// Pattern is the package pattern to scan (e.g., "./...", "./api/...")
Pattern string
// IgnorePaths contains path patterns to exclude during scanning
IgnorePaths []string
// OutputFile is the output file path for the generated spec
OutputFile string
// OutputFormat is the output format: "yaml" or "json"
OutputFormat string
// UseCache enables incremental build caching
UseCache bool
// Flatten inlines $ref schemas instead of using references
Flatten bool
// Validate enables spec validation after generation
Validate bool
// CleanUnused removes schemas that are declared but not referenced
CleanUnused bool
// NoDefault skips generating the default spec for routes without spec: directives
NoDefault bool
// EnumRefs generates enums as $ref references to components/schemas instead of inline
EnumRefs bool
}
Config holds configuration options for the generator.
type ConfigFile ¶
type ConfigFile struct {
CustomTypes map[string]TypeConfig `yaml:"customTypes"`
Schemas map[string]spec.Schema `yaml:"schemas"`
}
ConfigFile represents the .openapi.yaml configuration file.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator orchestrates the OpenAPI spec generation process.
func (*Generator) GenerateMulti ¶
GenerateMulti generates multiple OpenAPI specs based on spec: directives. Returns a map of spec name to OpenAPI spec.
func (*Generator) GenerateSpec ¶
GenerateSpec generates a single spec by name.
func (*Generator) GetSpecNames ¶
GetSpecNames returns all spec names that would be generated.
type Option ¶
type Option func(*Config)
Option is a function type for configuring the Generator.
func WithCleanUnused ¶
WithCleanUnused enables or disables removal of unreferenced schemas.
func WithEnumRefs ¶
WithEnumRefs enables generating enums as $ref references instead of inline.
func WithFlatten ¶
WithFlatten enables or disables schema flattening.
func WithIgnorePaths ¶
WithIgnorePaths sets the path patterns to ignore.
func WithNoDefault ¶
WithNoDefault skips generating the default spec for routes without spec: directives.
func WithOutput ¶
WithOutput sets the output file and format.
func WithPattern ¶
WithPattern sets the package pattern to scan.
func WithValidation ¶
WithValidation enables or disables spec validation.
type TypeConfig ¶
type TypeConfig struct {
Type string `yaml:"type"`
Format string `yaml:"format"`
Example any `yaml:"example"`
Default any `yaml:"default"`
}
TypeConfig represents a custom type configuration in the config file.
type TypeHandler ¶
type TypeHandler func(info *TypeInfo)
TypeHandler is a function that configures TypeInfo for a custom type.
type TypeInfo ¶
type TypeInfo struct {
Type string // OpenAPI type (string, integer, number, boolean, object, array)
Format string // OpenAPI format (uuid, date-time, decimal, etc.)
Example any // Example value
Default any // Default value
Validations map[string]string // Additional validations (pattern, minLength, etc.)
}
TypeInfo contains OpenAPI schema information for a custom type.
func GetCustomType ¶
GetCustomType returns the TypeInfo for a registered custom type. It tries an exact match first, then falls back to the short name (e.g., "decimal.Decimal" for "github.com/shopspring/decimal.Decimal"). Returns nil if the type is not registered.
Source Files