renderer

package
v0.37.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 27, 2026 License: MIT Imports: 22 Imported by: 10

Documentation

Index

Examples

Constants

View Source 
const (
	// Example is the field name used for a single mock example value.
	Example = "Example"

	// Examples is the field name used for named mock examples.
	Examples = "Examples"

	// Schema is the field name used for schema-based mock generation.
	Schema = "Schema"
)
View Source 
const (

	// DefaultMaxPatternRepeatBudget is the default regex repeat budget used when generating string mocks from patterns.
	DefaultMaxPatternRepeatBudget = 32

	// DefaultMaxGeneratedStringBytes is the default byte ceiling for each generated string mock value.
	DefaultMaxGeneratedStringBytes = 4096

	// DefaultMaxMockDepth is the default maximum recursive schema depth for generated mocks.
	DefaultMaxMockDepth = 100

	// DefaultMaxMockNodes is the default maximum number of schema nodes visited for a generated mock.
	DefaultMaxMockNodes = 10000

	// DefaultMaxMockProperties is the default maximum number of object properties rendered for a generated mock.
	DefaultMaxMockProperties = 5000

	// DefaultMaxMockRefExpansions is the default maximum number of reference expansions for a generated mock.
	DefaultMaxMockRefExpansions = 2000

	// DefaultMaxMockBytes is the default approximate generated mock byte budget before serialization.
	DefaultMaxMockBytes = 1024 * 1024
)

Variables

View Source 
var ErrMockGenerationBudgetExceeded = errors.New("mock generation budget exceeded")

ErrMockGenerationBudgetExceeded is wrapped by errors caused by configured mock generation budgets.

Functions

func ReadDictionary 

func ReadDictionary(dictionaryLocation string) []string

ReadDictionary reads a dictionary file and returns one entry per line.

Types

type MockGenerationBudgetError added in v0.36.5 

type MockGenerationBudgetError struct {
	// Budget is the name of the budget that was exceeded.
	Budget string
	// Limit is the configured budget value.
	Limit int
	// Actual is the observed value that exceeded the limit.
	Actual int
}

MockGenerationBudgetError describes which mock generation budget was exceeded.

func (*MockGenerationBudgetError) Error added in v0.36.5 

func (e *MockGenerationBudgetError) Error() string

func (*MockGenerationBudgetError) Unwrap added in v0.36.5 

func (e *MockGenerationBudgetError) Unwrap() error

Unwrap returns ErrMockGenerationBudgetExceeded for errors.Is checks.

type MockGenerationOptions added in v0.36.5 

type MockGenerationOptions struct {
	// MaxPatternRepeatBudget limits the repeat budget passed to regex-based string generation.
	MaxPatternRepeatBudget int
	// MaxGeneratedStringBytes limits the final size of generated string values.
	MaxGeneratedStringBytes int
	// MaxMockDepth limits recursive schema depth while building mock structures.
	MaxMockDepth int
	// MaxMockNodes limits the number of schema nodes visited while building a mock.
	MaxMockNodes int
	// MaxMockProperties limits the number of object properties rendered while building a mock.
	MaxMockProperties int
	// MaxMockRefExpansions limits the number of $ref schema expansions while building a mock.
	MaxMockRefExpansions int
	// MaxMockBytes limits approximate mock structure size before serialization.
	MaxMockBytes int
}

MockGenerationOptions controls how much work the renderer may spend generating mock values.

Zero or negative values use the package defaults. OpenAPI schema constraints such as maxLength are still used as validity hints, but they are not treated as permission to perform unbounded generation work.

type MockGenerator 

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

MockGenerator generates mocks for high-level mockable structs or *base.Schema pointers.

Mockable structs can provide the following fields:

  • Example: any type, this is the default example to use if no examples are present.
  • Examples: *orderedmap.Map[string, *base.Example], this is a map of examples keyed by name.
  • Schema: *base.SchemaProxy, this is the schema to use if no examples are present.

Use NewMockGenerator or NewMockGeneratorWithDictionary to create a new mock generator.

Example (GenerateBurgerMock_yaml) 
// create a new YAML mock generator
mg := NewMockGenerator(YAML)

burgerShop, _ := os.ReadFile("../test_specs/burgershop.openapi.yaml")

// create a new document from specification and build a v3 model.
document, _ := libopenapi.NewDocument(burgerShop)
v3Model, _ := document.BuildV3Model()

// create a mock of the Burger model
burgerModel := v3Model.Model.Components.Schemas.GetOrZero("Burger")
burger := burgerModel.Schema()
mock, err := mg.GenerateMock(burger, "")
if err != nil {
	panic(err)
}
fmt.Println(string(mock))

Output:
name: Big Mac
numPatties: 2
Example (GenerateFriesMock_json) 
// create a new YAML mock generator
mg := NewMockGenerator(JSON)

burgerShop, _ := os.ReadFile("../test_specs/burgershop.openapi.yaml")

// create a new document from specification and build a v3 model.
document, _ := libopenapi.NewDocument(burgerShop)
v3Model, _ := document.BuildV3Model()

// create a mock of the Fries model
friesModel := v3Model.Model.Components.Schemas.GetOrZero("Fries")
fries := friesModel.Schema()
mock, err := mg.GenerateMock(fries, "")
if err != nil {
	panic(err)
}
fmt.Println(string(mock))

Output:
{"favoriteDrink":{"drinkType":"coke","size":"M"},"potatoShape":"Crispy Shoestring"}
Example (GeneratePolymorphicMock_json) 
mg := NewMockGenerator(JSON)
// create a new YAML mock generator

burgerShop, _ := os.ReadFile("../test_specs/burgershop.openapi.yaml")

// create a new document from specification and build a v3 model.
document, _ := libopenapi.NewDocument(burgerShop)
v3Model, _ := document.BuildV3Model()

// create a mock of the SomePayload component, which uses polymorphism (incorrectly)
payloadModel := v3Model.Model.Components.Schemas.GetOrZero("SomePayload")
payload := payloadModel.Schema()
mock, err := mg.GenerateMock(payload, "")
if err != nil {
	panic(err)
}
fmt.Println(string(mock))

Output:
{"drinkType":"coke","size":"M"}
Example (GenerateRequestMock_json) 
// create a new YAML mock generator
mg := NewMockGenerator(JSON)

burgerShop, _ := os.ReadFile("../test_specs/burgershop.openapi.yaml")

// create a new document from specification and build a v3 model.
document, _ := libopenapi.NewDocument(burgerShop)
v3Model, _ := document.BuildV3Model()

// create a mock of the burger request model, extracted from the operation directly.
burgerRequestModel := v3Model.Model.Paths.PathItems.GetOrZero("/burgers").
	Post.RequestBody.Content.GetOrZero("application/json")

// use the 'cakeBurger' example to generate a mock
mock, err := mg.GenerateMock(burgerRequestModel, "cakeBurger")
if err != nil {
	panic(err)
}
fmt.Println(string(mock))

Output:
{"name":"Chocolate Cake Burger","numPatties":5}
Example (GenerateResponseMock_json) 
mg := NewMockGenerator(JSON)
// create a new YAML mock generator

burgerShop, _ := os.ReadFile("../test_specs/burgershop.openapi.yaml")

// create a new document from specification and build a v3 model.
document, _ := libopenapi.NewDocument(burgerShop)
v3Model, _ := document.BuildV3Model()

// create a mock of the burger response model, extracted from the operation directly.
burgerResponseModel := v3Model.Model.Paths.PathItems.GetOrZero("/burgers").
	Post.Responses.Codes.GetOrZero("200").Content.GetOrZero("application/json")

// use the 'filetOFish' example to generate a mock
mock, err := mg.GenerateMock(burgerResponseModel, "filetOFish")
if err != nil {
	panic(err)
}
fmt.Println(string(mock))

Output:
{"name":"Filet-O-Fish","numPatties":1}

func NewMockGenerator 

func NewMockGenerator(mockType MockType) *MockGenerator

NewMockGenerator creates a MockGenerator using the default dictionary.

The default is located at /usr/share/dict/words on most systems. Windows users need to use NewMockGeneratorWithDictionary to specify a custom dictionary.

func NewMockGeneratorWithDictionary 

func NewMockGeneratorWithDictionary(dictionaryLocation string, mockType MockType) *MockGenerator

NewMockGeneratorWithDictionary creates a MockGenerator using a custom dictionary file.

The location of a text file with one word per line is expected.

func (*MockGenerator) DisableRequiredCheck added in v0.16.8 

func (mg *MockGenerator) DisableRequiredCheck()

DisableRequiredCheck disables required-property filtering when rendering schema-based mocks.

When disabled, all properties are rendered, not just required properties.

func (*MockGenerator) GenerateMock 

func (mg *MockGenerator) GenerateMock(mock any, name string) ([]byte, error)

GenerateMock generates a mock for a high-level mockable struct or *base.Schema pointer.

The name parameter is optional. When provided, GenerateMock attempts to select a matching named example. If name is empty, the first available example is used.

func (*MockGenerator) RenderXML added in v0.36.0 

func (mg *MockGenerator) RenderXML(value any, schema *highbase.Schema) []byte

RenderXML renders a value as XML. If schema is provided, uses its XML metadata (xml.name, xml.attribute, xml.namespace, xml.prefix, xml.wrapped) for correct output. If schema is nil, falls back to basic element-based XML using map keys as element names.

Note: nodeType "cdata" is treated as "text" in this version because Go's xml.Encoder has no first-class CDATA token support.

func (*MockGenerator) SetMockGenerationOptions added in v0.36.5 

func (mg *MockGenerator) SetMockGenerationOptions(options MockGenerationOptions)

SetMockGenerationOptions sets work and output budgets for generated mock values.

Zero or negative option values are replaced with the package defaults.

func (*MockGenerator) SetPretty 

func (mg *MockGenerator) SetPretty()

SetPretty configures JSON mocks to render with indentation and newlines.

JSON mocks render as a single line by default. This option affects only JSON; YAML is always rendered in YAML form.

func (*MockGenerator) SetSeed added in v0.25.4 

func (mg *MockGenerator) SetSeed(seed int64)

SetSeed sets a specific seed for the random number generator used by this mock generator. This is useful for generating deterministic mocks for testing purposes.

func (*MockGenerator) SetUnresolvedRefHandler added in v0.36.0 

func (mg *MockGenerator) SetUnresolvedRefHandler(handler UnresolvedRefHandler)

SetUnresolvedRefHandler sets a callback that is invoked when a $ref cannot be resolved during mock rendering.

type MockType 

type MockType int

MockType identifies the output format generated by MockGenerator. 

const (
	// JSON renders mocks as JSON.
	JSON MockType = iota

	// YAML renders mocks as YAML.
	YAML

	// XML renders mocks as XML.
	XML
)

type SchemaRenderer 

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

SchemaRenderer generates mock values from schemas, examples and schema constraints.

When a dictionary is configured, it is used as the source for generated words.

func CreateRendererUsingDefaultDictionary 

func CreateRendererUsingDefaultDictionary() *SchemaRenderer

CreateRendererUsingDefaultDictionary creates a SchemaRenderer using the default dictionary file.

The default dictionary is located at /usr/share/dict/words on most systems. Windows users need to use CreateRendererUsingDictionary to specify a custom dictionary.

func CreateRendererUsingDictionary 

func CreateRendererUsingDictionary(dictionaryLocation string) *SchemaRenderer

CreateRendererUsingDictionary creates a SchemaRenderer using a custom dictionary file.

The location of a text file with one word per line is expected.

func (*SchemaRenderer) DisableRequiredCheck added in v0.13.12 

func (wr *SchemaRenderer) DisableRequiredCheck()

DisableRequiredCheck disables required-property filtering when rendering a schema.

When disabled, all properties are rendered, not just required properties. https://github.com/pb33f/libopenapi/issues/200

func (*SchemaRenderer) DiveIntoSchema 

func (wr *SchemaRenderer) DiveIntoSchema(schema *base.Schema, key string, structure map[string]any, visited map[string]bool, depth int) bool

DiveIntoSchema renders a schema into structure at key.

Examples are preferred. If no examples are available, the renderer generates a value from the schema type, format and pattern.

func (*SchemaRenderer) PseudoUUID 

func (wr *SchemaRenderer) PseudoUUID() string

PseudoUUID returns a UUID-shaped random value for mock data.

func (*SchemaRenderer) RandomFloat64 

func (wr *SchemaRenderer) RandomFloat64() float64

RandomFloat64 returns a random float64 between 0 and 1.

func (*SchemaRenderer) RandomInt 

func (wr *SchemaRenderer) RandomInt(min, max int64) int64

RandomInt returns a random integer between min and max.

func (*SchemaRenderer) RandomWord 

func (wr *SchemaRenderer) RandomWord(min, max int64, depth int) string

RandomWord returns a random word between the min and max lengths.

If no dictionary is configured, RandomWord returns a generated alphabetic string. Set min and max to 0 to return the selected dictionary word without length filtering. The depth parameter prevents unbounded retries.

func (*SchemaRenderer) RenderSchema 

func (wr *SchemaRenderer) RenderSchema(schema *base.Schema) any

RenderSchema renders a schema into a value that can be serialized as JSON or YAML.

RenderSchema preserves its historical best-effort behavior. Use RenderSchemaWithError to enforce and inspect mock generation work budget failures.

func (*SchemaRenderer) RenderSchemaWithError added in v0.36.5 

func (wr *SchemaRenderer) RenderSchemaWithError(schema *base.Schema) (any, error)

RenderSchemaWithError renders a schema into a value that can be serialized as JSON or YAML.

If mock generation exceeds a configured work budget, the returned error wraps ErrMockGenerationBudgetExceeded.

func (*SchemaRenderer) SetMockGenerationOptions added in v0.36.5 

func (wr *SchemaRenderer) SetMockGenerationOptions(options MockGenerationOptions)

SetMockGenerationOptions sets work and output budgets for generated mock values.

Zero or negative option values are replaced with the package defaults.

func (*SchemaRenderer) SetSeed added in v0.25.4 

func (wr *SchemaRenderer) SetSeed(seed int64)

SetSeed sets a specific seed for the random number generator used by this renderer. This is useful for generating deterministic mocks for testing purposes.

func (*SchemaRenderer) SetUnresolvedRefHandler added in v0.36.0 

func (wr *SchemaRenderer) SetUnresolvedRefHandler(handler UnresolvedRefHandler)

SetUnresolvedRefHandler sets a callback that is invoked when a $ref cannot be resolved during rendering.

type UnresolvedRefHandler added in v0.36.0 

type UnresolvedRefHandler func(propertyName string, proxy *base.SchemaProxy, err error)

UnresolvedRefHandler is called when a $ref property cannot be resolved during rendering.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.