📖 3 min read (~ 500 words).

Examples & defaults

Example values and defaults are documentation that travels with the schema: an example: shows a caller what a value looks like, a default: declares what the field is when the caller omits it. Both are typed to the field — a numeric default on an integer field is a JSON number, not a string. The panes below pair the annotated Go with the fragment the scanner emits, from the test-covered docs/examples/concepts/examples package.

For the exact value shapes these keywords accept, see Keywords.

example

example: <value> attaches an example to the property, coerced to the field’s type — Hello, world! stays a string, 3 becomes a number.

Annotated Go
// Greeting carries an example value for documentation.
//
// swagger:model
type Greeting struct {
	// Message is the greeting text.
	//
	// example: Hello, world!
	Message string `json:"message"`

	// Count is how many times to repeat it.
	//
	// example: 3
	Count int32 `json:"count"`
}

Full source: docs/examples/concepts/examples/examples.go

#/definitions/Greeting
{
  "type": "object",
  "title": "Greeting carries an example value for documentation.",
  "properties": {
    "count": {
      "description": "Count is how many times to repeat it.",
      "type": "integer",
      "format": "int32",
      "x-go-name": "Count",
      "example": 3
    },
    "message": {
      "description": "Message is the greeting text.",
      "type": "string",
      "x-go-name": "Message",
      "example": "Hello, world!"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/examples"
}

Full source: docs/examples/concepts/examples/testdata/example.json

default

default: <value> sets the property’s default, again typed to the field — 8080 is a number, false a boolean, auto a string.

Annotated Go
// Settings carries default values applied when a field is omitted.
//
// swagger:model
type Settings struct {
	// Port is the listen port.
	//
	// default: 8080
	Port int32 `json:"port"`

	// Mode is the run mode.
	//
	// default: auto
	Mode string `json:"mode"`

	// Verbose toggles verbose logging.
	//
	// default: false
	Verbose bool `json:"verbose"`
}

Full source: docs/examples/concepts/examples/examples.go

#/definitions/Settings
{
  "type": "object",
  "title": "Settings carries default values applied when a field is omitted.",
  "properties": {
    "mode": {
      "description": "Mode is the run mode.",
      "type": "string",
      "default": "auto",
      "x-go-name": "Mode"
    },
    "port": {
      "description": "Port is the listen port.",
      "type": "integer",
      "format": "int32",
      "default": 8080,
      "x-go-name": "Port"
    },
    "verbose": {
      "description": "Verbose toggles verbose logging.",
      "type": "boolean",
      "default": false,
      "x-go-name": "Verbose"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/examples"
}

Full source: docs/examples/concepts/examples/testdata/default.json

swagger:default

swagger:default is a narrow, value-only classifier hint placed on a var or const. It does not publish a spec entity of its own — it has no standalone output — so most spec defaults are carried by the default: keyword above rather than this annotation.

// DefaultPort is the fallback port used wherever Port is not supplied. The
// swagger:default annotation is a narrow value-only discovery hint.
//
// swagger:default
var DefaultPort = 8080

Full source: docs/examples/concepts/examples/examples.go

What’s next