swagger:description

// Widget is the Go-facing widget doc, written for Go readers.
//
// It explains internal Go usage that should not leak into the API spec.
//
// swagger:model
// swagger:title A Public Widget
// swagger:description A widget exposed via the public API.
type Widget struct {
	// ID explains the Go field for Go readers.
	//
	// swagger:description The unique widget identifier.
	ID string `json:"id"`

	// Label is the Go-facing field doc. Fields carry no title by default;
	// the override is the only way a property gets one.
	//
	// swagger:title Display Label
	// swagger:description Human-readable label shown to API consumers.
	Label string `json:"label"`

	// Plain keeps its godoc description because it carries no override.
	Plain string `json:"plain"`

	// Capacity combines a description override with an inline validation
	// keyword on the same field: the override applies AND maximum is kept,
	// because the override annotations dispatch through the schema family.
	//
	// swagger:description The maximum capacity, in liters.
	// maximum: 1000
	Capacity int64 `json:"capacity"`

	// Suppressed has a godoc that a bare swagger:description suppresses: the
	// empty value is applied (description omitted) and scan.empty-override is
	// raised, in case the bare marker was left behind by mistake.
	//
	// swagger:description
	Suppressed string `json:"suppressed"`

	// Notes carries a multi-line description override: the lines following the
	// annotation fold into the description until the blank line, joined with
	// newlines.
	//
	// swagger:description Free-form notes about the widget.
	// They may span several lines, all folded into one description.
	//
	// The blank line above terminates the override body; this paragraph is
	// ordinary godoc and is discarded (the override won).
	Notes string `json:"notes"`

	// Gadget is a $ref field carrying title + description overrides. They are
	// symmetric $ref siblings: kept under EmitRefSiblings, dropped to a bare
	// $ref under the default flags — the same rule a prose description follows.
	//
	// swagger:title Gadget Ref
	// swagger:description The attached gadget, described for API consumers.
	Gadget Gadget `json:"gadget"`
}

// Gadget is a plain referenced model.
//
// swagger:model
type Gadget struct {
	Serial string `json:"serial"`
}

{
  "description": "A widget exposed via the public API.",
  "type": "object",
  "title": "A Public Widget",
  "properties": {
    "capacity": {
      "description": "The maximum capacity, in liters.",
      "type": "integer",
      "format": "int64",
      "maximum": 1000,
      "x-go-name": "Capacity"
    },
    "gadget": {
      "$ref": "#/definitions/Gadget"
    },
    "id": {
      "description": "The unique widget identifier.",
      "type": "string",
      "x-go-name": "ID"
    },
    "label": {
      "description": "Human-readable label shown to API consumers.",
      "type": "string",
      "title": "Display Label",
      "x-go-name": "Label"
    },
    "notes": {
      "description": "Free-form notes about the widget.\nThey may span several lines, all folded into one description.",
      "type": "string",
      "x-go-name": "Notes"
    },
    "plain": {
      "description": "Plain keeps its godoc description because it carries no override.",
      "type": "string",
      "x-go-name": "Plain"
    },
    "suppressed": {
      "type": "string",
      "x-go-name": "Suppressed"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/overrides"
}

// Markdown opts into a verbatim body with the literal block marker.
//
// swagger:description |
// The body is captured **verbatim** — pipes, blank lines and all:
//
// | name | purpose |
// |------|---------|
// | foo  | bars    |
//
// - point one
// - point two
//
// swagger:model Markdown
type Markdown struct {
	// Name of the widget.
	//
	// swagger:description |
	// The name must be:
	//
	//   1. unique
	//   2. lowercase
	Name string `json:"name"`
}

{
  "description": "The body is captured **verbatim** — pipes, blank lines and all:\n\n| name | purpose |\n|------|---------|\n| foo  | bars    |\n\n- point one\n- point two",
  "type": "object",
  "title": "Markdown opts into a verbatim body with the literal block marker.",
  "properties": {
    "name": {
      "description": "The name must be:\n\n  1. unique\n  2. lowercase",
      "type": "string",
      "x-go-name": "Name"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/shaping/markdowndesc"
}