schema

Documentation

Overview

Package schema provides schema generation from Go types using reflection.

The SchemaGenerator type converts Go types to OpenAPI schemas, handling structs, slices, maps, primitives, and validation constraints from struct tags. It tracks seen types to avoid infinite recursion and creates component schema references for complex types.

Index

• type ParamSpec
• type RequestMetadata
  • func IntrospectRequest(t reflect.Type) *RequestMetadata
• type SchemaGenerator
  • func NewSchemaGenerator() *SchemaGenerator
  • func (sg *SchemaGenerator) Generate(t reflect.Type) *model.Schema
  • func (sg *SchemaGenerator) GenerateProjected(t reflect.Type, include func(reflect.StructField) bool) *model.Schema
  • func (sg *SchemaGenerator) GetComponentSchemas() map[string]*model.Schema

Types

type ParamSpec

type ParamSpec struct {
	Name        string
	In          string
	Description string
	Format      string
	Required    bool
	Type        reflect.Type
	Default     any
	Example     any
	Enum        []string
	Style       string // "simple", "matrix", "label" for path params
	Explode     *bool  // nil = use default; true/false = explicit
}

ParamSpec describes a single parameter extracted from struct tags.

It contains all information needed to generate an OpenAPI Parameter, including location (query, path, header, cookie), type, validation rules, and documentation.

type RequestMetadata

type RequestMetadata struct {
	Parameters []ParamSpec
	HasBody    bool
	BodyType   reflect.Type
}

RequestMetadata contains auto-discovered information about a request struct.

This metadata is extracted from struct tags compatible with the binding package, enabling automatic OpenAPI parameter and body schema generation.

func IntrospectRequest

func IntrospectRequest(t reflect.Type) *RequestMetadata

IntrospectRequest analyzes a request struct type and extracts OpenAPI metadata.

This function automatically discovers:

• Query parameters from `query` tags
• Path parameters from `path` tags
• Header parameters from `header` tags
• Cookie parameters from `cookie` tags
• Request body presence from `json` tags

Returns nil if the type is not a struct or pointer to struct.

type SchemaGenerator

type SchemaGenerator struct {
	// contains filtered or unexported fields
}

SchemaGenerator generates Schema from Go types using reflection.

It handles Go's type system and converts it to the version-agnostic model format, including support for structs, slices, maps, primitives, and common types like time.Time. The generator tracks seen types to avoid infinite recursion and creates component schema references for complex types.

func NewSchemaGenerator

func NewSchemaGenerator() *SchemaGenerator

NewSchemaGenerator creates a new schema generator.

The generator maintains internal state to track seen types and generated component schemas. A new generator should be created for each spec build.

func (*SchemaGenerator) Generate

func (sg *SchemaGenerator) Generate(t reflect.Type) *model.Schema

Generate generates a Schema for the given Go type.

func (*SchemaGenerator) GenerateProjected

func (sg *SchemaGenerator) GenerateProjected(t reflect.Type, include func(reflect.StructField) bool) *model.Schema

GenerateProjected builds a schema containing ONLY fields that satisfy include(f).

func (*SchemaGenerator) GetComponentSchemas

func (sg *SchemaGenerator) GetComponentSchemas() map[string]*model.Schema

GetComponentSchemas returns all generated component schemas.