build

type Builder ¶

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

Builder builds OpenAPI specifications from enriched route information.

A Builder accumulates API metadata (servers, tags, security schemes) and generates a version-agnostic specification from route definitions. The specification can then be projected to any OpenAPI version using the export package.

func NewBuilder(info model.Info) *Builder

func (b *Builder) AddSecurityScheme(name string, s *model.SecurityScheme) *Builder

func (b *Builder) AddServer(url, desc string) *Builder

func (b *Builder) AddServerVariable(name string, variable *model.ServerVariable) *Builder

func (b *Builder) AddServerWithExtensions(url, desc string, extensions map[string]any) *Builder

func (b *Builder) AddTag(name, desc string) *Builder

func (b *Builder) AddTagWithExtensions(name, desc string, extensions map[string]any) *Builder

func (b *Builder) AddTagWithExternalDocs(name, desc string, extDocs *model.ExternalDocs, extensions map[string]any) *Builder

func (b *Builder) Build(routes []EnrichedRoute) (*model.Spec, error)

func (b *Builder) SetExternalDocs(docs *model.ExternalDocs) *Builder

func (b *Builder) SetGlobalSecurity(reqs []model.SecurityRequirement) *Builder

type ConstraintKind ¶ added in v0.2.0

type ConstraintKind uint8

ConstraintKind represents the type of constraint on a path parameter.

const (
	ConstraintNone     ConstraintKind = iota
	ConstraintInt                     // OpenAPI: type integer, format int64
	ConstraintFloat                   // OpenAPI: type number, format double
	ConstraintUUID                    // OpenAPI: type string, format uuid
	ConstraintRegex                   // OpenAPI: type string, pattern
	ConstraintEnum                    // OpenAPI: type string, enum
	ConstraintDate                    // OpenAPI: type string, format date
	ConstraintDateTime                // OpenAPI: type string, format date-time
)

type EnrichedRoute ¶

type EnrichedRoute struct {
	RouteInfo RouteInfo
	Doc       *RouteDoc
}

EnrichedRoute combines route information with OpenAPI documentation.

This type is used to pass route data to Builder.Build() for spec generation. The Doc field may be nil if the route has no OpenAPI documentation.

type ExampleData ¶ added in v0.2.0

type ExampleData struct {
	Name          string
	Summary       string
	Description   string
	Value         any
	ExternalValue string
}

ExampleData holds example data to avoid import cycles with openapi package.

type PathConstraint ¶ added in v0.2.0

type PathConstraint struct {
	Kind    ConstraintKind
	Pattern string   // for ConstraintRegex
	Enum    []string // for ConstraintEnum
}

PathConstraint describes a typed constraint for a path parameter. These constraints map directly to OpenAPI schema types.

type RouteDoc ¶

type RouteDoc struct {
	Summary               string
	Description           string
	OperationID           string
	Tags                  []string
	Deprecated            bool
	Consumes              []string
	Produces              []string
	RequestType           reflect.Type
	RequestMetadata       *schema.RequestMetadata
	RequestExample        any           // Single unnamed example
	RequestNamedExamples  []ExampleData // Named examples
	ResponseTypes         map[int]reflect.Type
	ResponseExample       map[int]any           // Single unnamed example per status
	ResponseNamedExamples map[int][]ExampleData // Named examples per status
	Security              []SecurityReq
	Extensions            map[string]any // Operation-level extensions (x-*)
}

RouteDoc holds all OpenAPI metadata for a route. This is a copy of the openapi.RouteDoc structure to avoid import cycles.

type RouteInfo ¶

type RouteInfo struct {
	Method          string                    // HTTP method (GET, POST, etc.)
	Path            string                    // URL path with parameters (e.g. "/users/:id")
	PathConstraints map[string]PathConstraint // Typed constraints for path parameters
}

RouteInfo contains basic route information needed for OpenAPI generation. This avoids importing the openapi package to prevent import cycles.

type SecurityReq ¶

type SecurityReq struct {
	Scheme string
	Scopes []string
}

SecurityReq represents a security requirement for an operation.