Examples Package

pkg/examples generates example values for OpenAPI schemas by inspecting Go struct fields, types, and tags. It powers the automatic example population in the docs UI.

import "github.com/gopackx/open-swag-go/pkg/examples"

Config

type Config struct {
    UseFaker     bool                   // Use the Faker for realistic values
    TypeExamples map[string]interface{} // Per-format default examples
}

When TypeExamples is nil, New falls back to DefaultTypeExamples().

Generator

Produces example values for Go types.

type Generator struct {
    // unexported fields
}
 
func New(config Config) *Generator
func DefaultTypeExamples() map[string]interface{}

Methods

func (g *Generator) Generate(t interface{}) interface{}

Accepts any Go value and returns a populated example. Struct fields with an example tag use the tag value; other fields are inferred from the field name and type.

func (g *Generator) GenerateJSON(t interface{}) map[string]interface{}

Returns the example as a map[string]interface{}, ready to embed into an OpenAPI spec.

Usage

type User struct {
    ID    int64  `json:"id"    example:"42"`
    Name  string `json:"name"  example:"Alice"`
    Email string `json:"email"`
}
 
gen := examples.New(examples.Config{UseFaker: true})
ex := gen.Generate(User{})

Coercion of string example:"..." tag values to typed values (e.g. int64(42) instead of "42") is handled by schema.ConvertExampleToType in pkg/schema, and is applied automatically during schema/example generation.

Faker

Low-level value generator that produces realistic data.

type Faker struct {
    // unexported fields
}
 
func NewFaker() *Faker

Methods

func (f *Faker) String() string
func (f *Faker) Name() string
func (f *Faker) Email() string
func (f *Faker) Phone() string
func (f *Faker) URL() string
func (f *Faker) UUID() string
func (f *Faker) Int(min, max int) int
func (f *Faker) Float(min, max float64) float64
func (f *Faker) Bool() bool
func (f *Faker) Date() string
func (f *Faker) DateTime() string
func (f *Faker) IPv4() string
func (f *Faker) Sentence() string
func (f *Faker) Paragraph() string

Usage

faker := examples.NewFaker()
 
email := faker.Email()        // "alice@example.com"
price := faker.Float(1, 100)  // e.g. 29.99
id := faker.Int(1, 1000)      // e.g. 42
name := faker.Name()          // e.g. "Alice Johnson"

TemplateRegistry

A registry of named example templates.

func NewTemplateRegistry() *TemplateRegistry
 
func (r *TemplateRegistry) Register(name string, template Template)
func (r *TemplateRegistry) Get(name string) (Template, bool)
func (r *TemplateRegistry) GetValue(name string) (any, bool)
func (r *TemplateRegistry) All() map[string]Template

Quick Example

package main
 
import (
    "encoding/json"
    "fmt"
 
    "github.com/gopackx/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.Config{UseFaker: true})
    ex := gen.GenerateJSON(CreateUserRequest{})
    data, _ := json.MarshalIndent(ex, "", "  ")
    fmt.Println(string(data))
}

On this page