Examples Package
pkg/examples generates realistic example values for OpenAPI schemas by inspecting Go struct field names, types, and tags. It powers the automatic example population in the docs UI.
import "github.com/andrianprasetya/open-swag-go/pkg/examples"Generator
Produces example values for Go types.
type Generator struct {
// unexported fields
}
func New(opts ...Option) *GeneratorMethods
func (g *Generator) Generate(v interface{}) interface{}Accepts any Go value and returns a populated copy with realistic example data. Struct fields with an example tag use the tag value; other fields are inferred from the field name and type.
func (g *Generator) GenerateJSON(v interface{}) ([]byte, error)Same as Generate but returns the result as JSON bytes.
func (g *Generator) GenerateMap(v interface{}) map[string]interface{}Returns the example as a flat map, useful for injecting into OpenAPI spec examples.
Usage
type User struct {
ID int64 `json:"id" example:"42"`
Name string `json:"name" example:"Alice"`
Email string `json:"email"`
}
gen := examples.New()
ex := gen.Generate(User{})
// ex == User{ID: 42, Name: "Alice", Email: "alice@example.com"}Faker
Low-level value generator that produces realistic data based on field name heuristics.
type Faker struct {
// unexported fields
}
func NewFaker(opts ...Option) *FakerMethods
func (f *Faker) Value(fieldName string, fieldType reflect.Type) interface{}Returns a realistic value for the given field name and Go type. The field name is matched against built-in heuristics (see table below).
func (f *Faker) String(fieldName string) stringReturns a string value based on the field name.
func (f *Faker) Int(fieldName string) int64Returns an integer value based on the field name.
func (f *Faker) Float(fieldName string) float64Returns a float value based on the field name.
Field Name Heuristics
The Faker recognises common field names and generates appropriate values.
| Field Name Pattern | Generated Value |
|---|---|
id, *_id | Sequential integer (1, 2, 3…) |
name, *_name | Realistic name, e.g. "Alice Johnson" |
email, *_email | Email address, e.g. "alice@example.com" |
phone, *_phone | Phone number, e.g. "+1-555-0100" |
url, *_url, website | URL, e.g. "https://example.com" |
address, *_address | Street address |
city | City name |
country | Country name |
zip, postal_code | Postal code |
price, amount, *_price | Monetary value, e.g. 29.99 |
created_at, updated_at, *_at | ISO 8601 timestamp |
description, bio, summary | Lorem-style sentence |
status | "active" |
enabled, active, is_* | true |
Usage
faker := examples.NewFaker()
email := faker.String("email") // "alice@example.com"
price := faker.Float("price") // 29.99
userID := faker.Int("user_id") // 1Config
Functional options for customising the generator and faker behaviour.
type Option func(*config)func WithSeed(seed int64) OptionSets a fixed random seed for deterministic output. Useful for snapshot tests.
func WithLocale(locale string) OptionSets the locale for generated strings (e.g. "en", "de", "ja"). Defaults to "en".
func WithCustomField(pattern string, value interface{}) OptionRegisters a custom heuristic. When a field name matches the pattern, the provided value is used.
Usage
gen := examples.New(
examples.WithSeed(12345),
examples.WithCustomField("tenant_id", "org_abc123"),
)
type Order struct {
TenantID string `json:"tenant_id"`
ProductID int64 `json:"product_id" example:"7"`
Quantity int `json:"quantity"`
}
ex := gen.Generate(Order{})
// ex.TenantID == "org_abc123" (custom field)
// ex.ProductID == 7 (from example tag)
// ex.Quantity == 1 (default int)Quick Example
package main
import (
"encoding/json"
"fmt"
"github.com/andrianprasetya/open-swag-go/pkg/examples"
)
type CreateUserRequest struct {
Name string `json:"name" example:"Bob"`
Email string `json:"email"`
Age int `json:"age" example:"30"`
Country string `json:"country"`
}
func main() {
gen := examples.New(examples.WithSeed(1))
data, _ := gen.GenerateJSON(CreateUserRequest{})
fmt.Println(string(data))
// {"name":"Bob","email":"bob@example.com","age":30,"country":"United States"}
}