Examples Package

pkg/examples generates example values by inspecting Go struct fields, types, and tags. It is a standalone helper: BuildSpec does not use it, and examples in the generated spec come only from example:"..." tags.

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

Config

type Config struct {
    // TypeExamples maps a format name (e.g. "email", "uuid") to the example
    // value used for fields with that format. Nil means DefaultTypeExamples().
    TypeExamples map[string]interface{}
}

Generator

Produces example values for Go types.

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

New fills a nil TypeExamples with DefaultTypeExamples(), which returns a fresh map with examples for the formats uuid, email, uri, url, hostname, ipv4, ipv6, date, date-time, time, password, byte and binary.

Methods

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

Accepts any Go value and returns an example: a map[string]interface{} for a struct, a one-element slice for a slice, and a type default for scalars. Generate(nil) returns nil. For each exported struct field (named by its json tag, falling back to the Go field name; json:"-" is skipped) the first rule that applies wins: the example tag (converted to the field type), the format tag or the swagger tag's format=... looked up in TypeExamples, a field-name heuristic, then the type default. See Example Generator for the heuristics and defaults.

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

Like Generate, but returns the result as a map[string]interface{}, or nil when the example is not an object (for example a non-struct value).

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{})
ex := gen.GenerateJSON(User{})
// map[email:user@example.com id:42 name:Alice]

example tag values are converted by the generator itself: integers, unsigned integers, floats and booleans are parsed, slices and maps are parsed as JSON, and anything that does not parse stays a string. Schema generation uses schema.ConvertExampleToType in pkg/schema, which applies the same conversions and additionally turns example:"null" into JSON null; the generator keeps it as the string "null".

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{})
    ex := gen.GenerateJSON(CreateUserRequest{})
    data, _ := json.MarshalIndent(ex, "", "  ")
    fmt.Println(string(data))
}

Removed in v1.3.0: the fake-data helper, the example template registry and the matching Config switch. They were never used by the generator or the docs UI. See the Changelog.