// Pet is a single pet in the store.
//
// swagger:model
type Pet struct {
	// ID is the unique identifier.
	ID int64 `json:"id"`

	// Name is the pet's display name.
	Name string `json:"name"`

	// Tags categorise the pet.
	Tags []string `json:"tags,omitempty"`
}

{
  "type": "object",
  "title": "Pet is a single pet in the store.",
  "properties": {
    "id": {
      "description": "ID is the unique identifier.",
      "type": "integer",
      "format": "int64",
      "x-go-name": "ID"
    },
    "name": {
      "description": "Name is the pet's display name.",
      "type": "string",
      "x-go-name": "Name"
    },
    "tags": {
      "description": "Tags categorise the pet.",
      "type": "array",
      "items": {
        "type": "string"
      },
      "x-go-name": "Tags"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

// MAC is a hardware address rendered as a colon-separated hex string.
//
// swagger:strfmt mac
type MAC string

func (m MAC) MarshalText() ([]byte, error)  { return []byte(m), nil }
func (m *MAC) UnmarshalText(b []byte) error { *m = MAC(b); return nil }

// Device exposes a strfmt-typed field: wherever MAC appears it renders inline
// as {type: string, format: mac}.
//
// swagger:model
type Device struct {
	// Addr is the hardware address.
	Addr MAC `json:"addr"`
}

{
  "description": "Device exposes a strfmt-typed field: wherever MAC appears it renders inline\nas {type: string, format: mac}.",
  "type": "object",
  "properties": {
    "addr": {
      "description": "Addr is the hardware address.",
      "type": "string",
      "format": "mac",
      "x-go-name": "Addr"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

// Priority is the urgency level on a task.
//
// swagger:enum Priority
type Priority string

const (
	// PriorityLow is for tasks that can wait.
	PriorityLow Priority = "low"
	// PriorityMedium is the default.
	PriorityMedium Priority = "medium"
	// PriorityHigh is for tasks that must run soon.
	PriorityHigh Priority = "high"
)

// Task is a unit of work carrying an enum-typed field. Referencing Priority
// from a model is what makes the enum reachable, and so emitted.
//
// swagger:model
type Task struct {
	// Priority is the task's urgency.
	Priority Priority `json:"priority"`
}

{
  "description": "Task is a unit of work carrying an enum-typed field. Referencing Priority\nfrom a model is what makes the enum reachable, and so emitted.",
  "type": "object",
  "properties": {
    "priority": {
      "description": "Priority is the task's urgency.\nlow PriorityLow is for tasks that can wait.\nmedium PriorityMedium is the default.\nhigh PriorityHigh is for tasks that must run soon.",
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "x-go-enum-desc": "low PriorityLow is for tasks that can wait.\nmedium PriorityMedium is the default.\nhigh PriorityHigh is for tasks that must run soon.",
      "x-go-name": "Priority"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

// Animal is one abstract base.
//
// swagger:model
type Animal struct {
	// Kind discriminates the animal.
	Kind string `json:"kind"`
}

// Tagged is a second reusable base.
//
// swagger:model
type Tagged struct {
	// Tags label the resource.
	Tags []string `json:"tags"`
}

// Dog composes two base models plus its own fields: each embedded base becomes
// a $ref arm of the allOf, and the struct's own (non-embedded) fields — which
// are new and cannot be a $ref — form the final inline arm.
//
// swagger:model
type Dog struct {
	// swagger:allOf
	Animal

	// swagger:allOf
	Tagged

	// Breed is the dog's breed.
	Breed string `json:"breed"`
}

{
  "description": "Dog composes two base models plus its own fields: each embedded base becomes\na $ref arm of the allOf, and the struct's own (non-embedded) fields — which\nare new and cannot be a $ref — form the final inline arm.",
  "allOf": [
    {
      "$ref": "#/definitions/Animal"
    },
    {
      "$ref": "#/definitions/Tagged"
    },
    {
      "type": "object",
      "properties": {
        "breed": {
          "description": "Breed is the dog's breed.",
          "type": "string",
          "x-go-name": "Breed"
        }
      }
    }
  ],
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

// ULID is a 128-bit identifier stored as bytes but rendered as a string.
//
// swagger:type string
type ULID [16]byte

// Token carries a field whose inferred type is overridden, inline.
//
// swagger:model
type Token struct {
	// ID renders as a string despite its [16]byte Go type.
	ID ULID `json:"id"`
}


// RawID is a custom 16-byte identifier — an array under the hood, so left to
// itself a field of this type would render as an array of integers.
type RawID [16]byte

// Coupon overrides the type of a single field directly on the field doc — no
// wrapper-type annotation. Code publishes as a bare string while RawID is left
// untouched everywhere else it appears.
//
// swagger:model
type Coupon struct {
	// Code is an opaque identifier published as a string.
	//
	// swagger:type string
	Code RawID `json:"code"`

	// Amount is the discount in cents.
	Amount int64 `json:"amount"`
}

{
  "type": "object",
  "title": "Token carries a field whose inferred type is overridden, inline.",
  "properties": {
    "id": {
      "description": "ID renders as a string despite its [16]byte Go type.",
      "type": "string",
      "x-go-name": "ID"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

// RawID is a custom 16-byte identifier — an array under the hood, so left to
// itself a field of this type would render as an array of integers.
type RawID [16]byte

// Coupon overrides the type of a single field directly on the field doc — no
// wrapper-type annotation. Code publishes as a bare string while RawID is left
// untouched everywhere else it appears.
//
// swagger:model
type Coupon struct {
	// Code is an opaque identifier published as a string.
	//
	// swagger:type string
	Code RawID `json:"code"`

	// Amount is the discount in cents.
	Amount int64 `json:"amount"`
}

{
  "description": "Coupon overrides the type of a single field directly on the field doc — no\nwrapper-type annotation. Code publishes as a bare string while RawID is left\nuntouched everywhere else it appears.",
  "type": "object",
  "properties": {
    "amount": {
      "description": "Amount is the discount in cents.",
      "type": "integer",
      "format": "int64",
      "x-go-name": "Amount"
    },
    "code": {
      "description": "Code is an opaque identifier published as a string.",
      "type": "string",
      "x-go-name": "Code"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

// Car is exposed as a schema via its method set. Interface methods cannot carry
// a json tag, so by default each property takes the camelCased method name;
// swagger:name overrides that where the default is not what you want.
//
// swagger:model
type Car interface {
	// Maker is the manufacturer. With no override the property is the
	// camelCased method name, "maker".
	Maker() string

	// StructType is the polymorphic class. Without the override the property
	// would be "structType"; swagger:name publishes it as "jsonClass".
	//
	// swagger:name jsonClass
	StructType() string
}


// Account shows the universal name: keyword renaming model struct fields. The
// same keyword used on parameters and response headers also sets a property key
// here, winning over a json tag, the legacy swagger:name annotation, and the Go
// field name.
//
// swagger:model
type Account struct {
	// Bal has no json tag; the keyword sets the property key directly.
	//
	// name: balance
	Bal float64

	// Currency carries both naming forms; the keyword wins over the
	// legacy annotation and the json tag.
	//
	// name: currencyCode
	// swagger:name legacyCurrency
	Currency string `json:"currency"`
}

{
  "description": "Car is exposed as a schema via its method set. Interface methods cannot carry\na json tag, so by default each property takes the camelCased method name;",
  "type": "object",
  "properties": {
    "jsonClass": {
      "description": "StructType is the polymorphic class. Without the override the property\nwould be \"structType\"; swagger:name publishes it as \"jsonClass\".",
      "type": "string",
      "x-go-name": "StructType"
    },
    "maker": {
      "description": "Maker is the manufacturer. With no override the property is the\ncamelCased method name, \"maker\".",
      "type": "string",
      "x-go-name": "Maker"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

// Account shows the universal name: keyword renaming model struct fields. The
// same keyword used on parameters and response headers also sets a property key
// here, winning over a json tag, the legacy swagger:name annotation, and the Go
// field name.
//
// swagger:model
type Account struct {
	// Bal has no json tag; the keyword sets the property key directly.
	//
	// name: balance
	Bal float64

	// Currency carries both naming forms; the keyword wins over the
	// legacy annotation and the json tag.
	//
	// name: currencyCode
	// swagger:name legacyCurrency
	Currency string `json:"currency"`
}

{
  "description": "Account shows the universal name: keyword renaming model struct fields. The\nsame keyword used on parameters and response headers also sets a property key\nhere, winning over a json tag, the legacy swagger:name annotation, and the Go\nfield name.",
  "type": "object",
  "properties": {
    "balance": {
      "description": "Bal has no json tag; the keyword sets the property key directly.",
      "type": "number",
      "format": "double",
      "x-go-name": "Bal"
    },
    "currencyCode": {
      "description": "Currency carries both naming forms; the keyword wins over the\nlegacy annotation and the json tag.",
      "type": "string",
      "x-go-name": "Currency"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

// Address is a referenced model.
//
// swagger:model
type Address struct {
	// Street is the street line.
	Street string `json:"street"`
}

// Person references Address through a field that also carries a description and
// a vendor extension. A bare $ref cannot hold sibling keywords, so codescan
// wraps the reference as a member of an allOf — the property is then a normal
// schema that keeps the description and the x-* extension, and required goes to
// the parent. Nothing is dropped.
//
// swagger:model
type Person struct {
	// Home is where the person lives.
	//
	// required: true
	// extensions:
	//   x-ui-order: 3
	Home Address `json:"home"`
}

{
  "description": "Person references Address through a field that also carries a description and\na vendor extension. A bare $ref cannot hold sibling keywords, so codescan\nwraps the reference as a member of an allOf — the property is then a normal\nschema that keeps the description and the x-* extension, and required goes to\nthe parent. Nothing is dropped.",
  "type": "object",
  "required": [
    "home"
  ],
  "properties": {
    "home": {
      "description": "Home is where the person lives.",
      "allOf": [
        {
          "$ref": "#/definitions/Address"
        }
      ],
      "x-go-name": "Home",
      "x-ui-order": 3
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/refoverride"
}

// Weekday is an iota enum: only the first spec carries a type and a value, and
// every following one inherits both implicitly.
//
// swagger:enum Weekday
type Weekday int

const (
	// Sunday is the first day.
	Sunday Weekday = iota
	// Monday is the second day.
	Monday
	// Tuesday is the third day.
	Tuesday
)

// Schedule carries the enum, which is what makes it reachable and so emitted.
//
// swagger:model
type Schedule struct {
	// Day the job runs on.
	Day Weekday `json:"day"`
}

{
  "type": "object",
  "title": "Schedule carries the enum, which is what makes it reachable and so emitted.",
  "properties": {
    "day": {
      "description": "Day the job runs on.\n0 Sunday is the first day.\n1 Monday is the second day.\n2 Tuesday is the third day.",
      "type": "integer",
      "format": "int64",
      "enum": [
        0,
        1,
        2
      ],
      "x-go-enum-desc": "0 Sunday is the first day.\n1 Monday is the second day.\n2 Tuesday is the third day.",
      "x-go-name": "Day"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

// Level is built from a constant expression and from a reference to an earlier
// member — neither of which is a literal.
//
// swagger:enum Level
type Level int

const (
	// LevelLow is the floor.
	LevelLow Level = 1 << 3
	// LevelHigh doubles it.
	LevelHigh Level = LevelLow * 2
)

// Threshold carries the computed enum.
//
// swagger:model
type Threshold struct {
	// Level to alert at.
	Level Level `json:"level"`
}

{
  "type": "object",
  "title": "Threshold carries the computed enum.",
  "properties": {
    "level": {
      "description": "Level to alert at.\n8 LevelLow is the floor.\n16 LevelHigh doubles it.",
      "type": "integer",
      "format": "int64",
      "enum": [
        8,
        16
      ],
      "x-go-enum-desc": "8 LevelLow is the floor.\n16 LevelHigh doubles it.",
      "x-go-name": "Level"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

// PanDirection straddles zero. A signed constant is not a literal in the Go
// grammar — it is an expression wrapping one — so these are the members that
// used to go missing.
//
// swagger:enum PanDirection
type PanDirection int8

const (
	// PanLeft pans to the left.
	PanLeft PanDirection = -1
	// NoPan holds the current position.
	NoPan PanDirection = 0
	// PanRight pans to the right.
	PanRight PanDirection = 1
)

// Camera carries the signed enum, declared int8.
//
// swagger:model
type Camera struct {
	// Pan direction of the camera.
	Pan PanDirection `json:"pan"`
}

{
  "type": "object",
  "title": "Camera carries the signed enum, declared int8.",
  "properties": {
    "pan": {
      "description": "Pan direction of the camera.\n-1 PanLeft pans to the left.\n0 NoPan holds the current position.\n1 PanRight pans to the right.",
      "type": "integer",
      "format": "int8",
      "enum": [
        -1,
        0,
        1
      ],
      "x-go-enum-desc": "-1 PanLeft pans to the left.\n0 NoPan holds the current position.\n1 PanRight pans to the right.",
      "x-go-name": "Pan"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

// Zoom is a float32 enum whose FIRST member is written as an integer literal.
// The schema type follows the declared type, so the block can be reordered
// freely.
//
// swagger:enum Zoom
type Zoom float32

const (
	// ZoomNone is the neutral step.
	ZoomNone Zoom = 0
	// ZoomOut steps back.
	ZoomOut Zoom = -1.5
	// ZoomIn steps in.
	ZoomIn Zoom = 1.5
)

// Lens carries the float enum.
//
// swagger:model
type Lens struct {
	// Zoom step of the lens.
	Zoom Zoom `json:"zoom"`
}

{
  "type": "object",
  "title": "Lens carries the float enum.",
  "properties": {
    "zoom": {
      "description": "Zoom step of the lens.\n0 ZoomNone is the neutral step.\n-1.5 ZoomOut steps back.\n1.5 ZoomIn steps in.",
      "type": "number",
      "format": "float",
      "enum": [
        0,
        -1.5,
        1.5
      ],
      "x-go-enum-desc": "0 ZoomNone is the neutral step.\n-1.5 ZoomOut steps back.\n1.5 ZoomIn steps in.",
      "x-go-name": "Zoom"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

// Kind is an enum written over a string format rather than over a plain string:
// the format of the type it is declared over comes with it.
//
// swagger:enum Kind
type Kind strfmt.UUID

const (
	// KindPrimary is the primary kind.
	KindPrimary Kind = "0a8bcf1e-0000-0000-0000-000000000000"
	// KindSecondary is the secondary kind.
	KindSecondary Kind = "0a8bcf1e-1111-1111-1111-111111111111"
)

// Label carries the formatted enum.
//
// swagger:model
type Label struct {
	// Kind of the label.
	Kind Kind `json:"kind"`
}

{
  "type": "object",
  "title": "Label carries the formatted enum.",
  "properties": {
    "kind": {
      "description": "Kind of the label.\n0a8bcf1e-0000-0000-0000-000000000000 KindPrimary is the primary kind.\n0a8bcf1e-1111-1111-1111-111111111111 KindSecondary is the secondary kind.",
      "type": "string",
      "format": "uuid",
      "enum": [
        "0a8bcf1e-0000-0000-0000-000000000000",
        "0a8bcf1e-1111-1111-1111-111111111111"
      ],
      "x-go-enum-desc": "0a8bcf1e-0000-0000-0000-000000000000 KindPrimary is the primary kind.\n0a8bcf1e-1111-1111-1111-111111111111 KindSecondary is the secondary kind.",
      "x-go-name": "Kind"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

// Letter is a rune enum. A rune is an int32, on the wire as much as in Go, so
// the members are code points — 'a' is 97.
//
// swagger:enum Letter
type Letter rune

const (
	// LetterA is the first letter.
	LetterA Letter = 'a'
	// LetterB is the second letter.
	LetterB Letter = 'b'
)

// Glyph carries the rune enum.
//
// swagger:model
type Glyph struct {
	// Letter of the glyph.
	Letter Letter `json:"letter"`
}

{
  "type": "object",
  "title": "Glyph carries the rune enum.",
  "properties": {
    "letter": {
      "description": "Letter of the glyph.\n97 LetterA is the first letter.\n98 LetterB is the second letter.",
      "type": "integer",
      "format": "int32",
      "enum": [
        97,
        98
      ],
      "x-go-enum-desc": "97 LetterA is the first letter.\n98 LetterB is the second letter.",
      "x-go-name": "Letter"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/enums"
}

// Inventory shows a plain Go map. A map renders as an object whose values all
// share one schema, carried as additionalProperties.
//
// swagger:model
type Inventory struct {
	// Counts maps each SKU to its on-hand quantity.
	Counts map[string]int `json:"counts"`
}

{
  "description": "Inventory shows a plain Go map. A map renders as an object whose values all\nshare one schema, carried as additionalProperties.",
  "type": "object",
  "properties": {
    "counts": {
      "description": "Counts maps each SKU to its on-hand quantity.",
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "format": "int64"
      },
      "x-go-name": "Counts"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

// Lookups shows which Go map keys survive. A key is usable when encoding/json
// can stringify it: string kinds, every integer/unsigned kind, and types
// implementing encoding.TextMarshaler. Other keys (float, bool, struct without
// TextMarshaler) are dropped with a diagnostic.
//
// swagger:model
type Lookups struct {
	// ByName is keyed by a plain string.
	ByName map[string]int `json:"byName"`

	// ByCode is keyed by an integer — JSON stringifies it, so the map is still
	// an object with additionalProperties.
	ByCode map[int]string `json:"byCode"`
}

{
  "description": "Lookups shows which Go map keys survive. A key is usable when encoding/json\ncan stringify it: string kinds, every integer/unsigned kind, and types\nimplementing encoding.TextMarshaler. Other keys (float, bool, struct without\nTextMarshaler) are dropped with a diagnostic.",
  "type": "object",
  "properties": {
    "byCode": {
      "description": "ByCode is keyed by an integer — JSON stringifies it, so the map is still\nan object with additionalProperties.",
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "x-go-name": "ByCode"
    },
    "byName": {
      "description": "ByName is keyed by a plain string.",
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "format": "int64"
      },
      "x-go-name": "ByName"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

{
  "description": "ClosedObject forbids any key beyond its named properties: the marker false\ncloses the object.",
  "type": "object",
  "properties": {
    "a": {
      "type": "string",
      "x-go-name": "A"
    },
    "b": {
      "type": "integer",
      "format": "int64",
      "x-go-name": "B"
    }
  },
  "additionalProperties": false,
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

{
  "type": "object",
  "title": "OpenObject keeps its named property and also allows arbitrary extra keys.",
  "properties": {
    "a": {
      "type": "string",
      "x-go-name": "A"
    }
  },
  "additionalProperties": true,
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

{
  "type": "object",
  "title": "TypedObject complements its named property with typed (integer) extra values.",
  "properties": {
    "a": {
      "type": "string",
      "x-go-name": "A"
    }
  },
  "additionalProperties": {
    "type": "integer"
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

{
  "type": "object",
  "title": "RefObject references a model as the schema of its extra values.",
  "properties": {
    "a": {
      "type": "string",
      "x-go-name": "A"
    }
  },
  "additionalProperties": {
    "$ref": "#/definitions/Thing"
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

// Holder decorates individual fields with the additionalProperties: keyword.
//
// swagger:model
type Holder struct {
	// OverriddenMap keeps its map shape but overrides the value schema from the
	// Go element type (string) to integer.
	//
	// additionalProperties: integer
	OverriddenMap map[string]string `json:"overriddenMap"`

	// RefMap points the map values at a model.
	//
	// additionalProperties: Thing
	RefMap map[string]string `json:"refMap"`

	// ClosedRef references a model and forbids extra keys. Because the field is
	// a $ref, the value rides an allOf sibling so the reference is preserved.
	//
	// additionalProperties: false
	ClosedRef Thing `json:"closedRef"`
}

{
  "type": "object",
  "title": "Holder decorates individual fields with the additionalProperties: keyword.",
  "properties": {
    "closedRef": {
      "description": "ClosedRef references a model and forbids extra keys. Because the field is\na $ref, the value rides an allOf sibling so the reference is preserved.",
      "allOf": [
        {
          "$ref": "#/definitions/Thing"
        },
        {
          "additionalProperties": false
        }
      ],
      "x-go-name": "ClosedRef"
    },
    "overriddenMap": {
      "description": "OverriddenMap keeps its map shape but overrides the value schema from the\nGo element type (string) to integer.",
      "type": "object",
      "additionalProperties": {
        "type": "integer"
      },
      "x-go-name": "OverriddenMap"
    },
    "refMap": {
      "description": "RefMap points the map values at a model.",
      "type": "object",
      "additionalProperties": {
        "$ref": "#/definitions/Thing"
      },
      "x-go-name": "RefMap"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

// TypedPatterns maps property-name regexes to typed value schemas. Each quoted
// regex pairs with a value spec — a primitive or a model name (which becomes a
// $ref). The pattern-properties keyword is JSON-Schema, beyond the Swagger 2.0
// subset; codescan emits it ungated.
//
// swagger:model
// swagger:patternProperties "^x-": string, "^\d+$": integer, "^item-": Thing
type TypedPatterns struct {
	Known string `json:"known"`
}

{
  "description": "TypedPatterns maps property-name regexes to typed value schemas. Each quoted\nregex pairs with a value spec — a primitive or a model name (which becomes a\n$ref). The pattern-properties keyword is JSON-Schema, beyond the Swagger 2.0\nsubset; codescan emits it ungated.",
  "type": "object",
  "properties": {
    "known": {
      "type": "string",
      "x-go-name": "Known"
    }
  },
  "patternProperties": {
    "^\\d+$": {
      "type": "integer"
    },
    "^item-": {
      "$ref": "#/definitions/Thing"
    },
    "^x-": {
      "type": "string"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

// Pet is the polymorphic base type. The field marked `discriminator: true` names
// the property whose value tells a consumer which concrete subtype a payload is:
// codescan writes that property's name onto the schema's `discriminator`, and a
// discriminator property must be `required`.
//
// swagger:model
type Pet struct {
	// PetType selects the concrete subtype — its value is the subtype's
	// definition name (e.g. "Cat" or "Dog").
	//
	// discriminator: true
	// required: true
	PetType string `json:"petType"`

	// Name is common to every pet.
	//
	// required: true
	Name string `json:"name"`
}

{
  "description": "Pet is the polymorphic base type. The field marked `discriminator: true` names\nthe property whose value tells a consumer which concrete subtype a payload is:\ncodescan writes that property's name onto the schema's `discriminator`, and a\ndiscriminator property must be `required`.",
  "type": "object",
  "required": [
    "petType",
    "name"
  ],
  "properties": {
    "name": {
      "description": "Name is common to every pet.",
      "type": "string",
      "x-go-name": "Name"
    },
    "petType": {
      "description": "PetType selects the concrete subtype — its value is the subtype's\ndefinition name (e.g. \"Cat\" or \"Dog\").",
      "type": "string",
      "x-go-name": "PetType"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/polymorphism",
  "discriminator": "petType"
}

// Cat is a Pet subtype. `swagger:allOf` composes it as
// `allOf: [ $ref Pet, {its own fields} ]` — the composition Swagger 2.0
// polymorphism builds on.
//
// swagger:model
type Cat struct {
	// swagger:allOf
	Pet

	// HuntingSkill is how the cat hunts.
	HuntingSkill string `json:"huntingSkill"`
}

// Dog is a second Pet subtype.
//
// swagger:model
type Dog struct {
	// swagger:allOf
	Pet

	// PackSize is the size of the dog's pack.
	PackSize int32 `json:"packSize"`
}

{
  "description": "Cat is a Pet subtype. `swagger:allOf` composes it as\n`allOf: [ $ref Pet, {its own fields} ]` — the composition Swagger 2.0\npolymorphism builds on.",
  "allOf": [
    {
      "$ref": "#/definitions/Pet"
    },
    {
      "type": "object",
      "properties": {
        "huntingSkill": {
          "description": "HuntingSkill is how the cat hunts.",
          "type": "string",
          "x-go-name": "HuntingSkill"
        }
      }
    }
  ],
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/polymorphism"
}

// PetResponse returns the polymorphic BASE — nothing in the API surface names
// Cat or Dog.
//
// swagger:response petResponse
type PetResponse struct {
	// in: body
	Body Pet `json:"body"`
}

// swagger:route GET /pets pets listPets
//
// Lists pets.
//
// responses:
//
//	200: petResponse

{
  "swagger": "2.0",
  "paths": {
    "/pets": {
      "get": {
        "tags": [
          "pets"
        ],
        "summary": "Lists pets.",
        "operationId": "listPets",
        "responses": {
          "200": {
            "$ref": "#/responses/petResponse"
          }
        }
      }
    }
  },
  "definitions": {
    "Cat": {
      "description": "Cat is a Pet subtype. `swagger:allOf` composes it as\n`allOf: [ $ref Pet, {its own fields} ]` — the composition Swagger 2.0\npolymorphism builds on.",
      "allOf": [
        {
          "$ref": "#/definitions/Pet"
        },
        {
          "type": "object",
          "properties": {
            "huntingSkill": {
              "description": "HuntingSkill is how the cat hunts.",
              "type": "string",
              "x-go-name": "HuntingSkill"
            }
          }
        }
      ],
      "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/polymorphism"
    },
    "Dog": {
      "title": "Dog is a second Pet subtype.",
      "allOf": [
        {
          "$ref": "#/definitions/Pet"
        },
        {
          "type": "object",
          "properties": {
            "packSize": {
              "description": "PackSize is the size of the dog's pack.",
              "type": "integer",
              "format": "int32",
              "x-go-name": "PackSize"
            }
          }
        }
      ],
      "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/polymorphism"
    },
    "Pet": {
      "description": "Pet is the polymorphic base type. The field marked `discriminator: true` names\nthe property whose value tells a consumer which concrete subtype a payload is:\ncodescan writes that property's name onto the schema's `discriminator`, and a\ndiscriminator property must be `required`.",
      "type": "object",
      "required": [
        "petType",
        "name"
      ],
      "properties": {
        "name": {
          "description": "Name is common to every pet.",
          "type": "string",
          "x-go-name": "Name"
        },
        "petType": {
          "description": "PetType selects the concrete subtype — its value is the subtype's\ndefinition name (e.g. \"Cat\" or \"Dog\").",
          "type": "string",
          "x-go-name": "PetType"
        }
      },
      "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/polymorphism",
      "discriminator": "petType"
    }
  },
  "responses": {
    "petResponse": {
      "description": "PetResponse returns the polymorphic BASE — nothing in the API surface names\nCat or Dog.",
      "schema": {
        "$ref": "#/definitions/Pet"
      }
    }
  }
}

// Shape is the root of the hierarchy: a base written as an interface, whose
// `discriminator: true` member names the property a consumer switches on.
//
// swagger:model
type Shape interface {
	// ShapeType selects the concrete subtype.
	//
	// discriminator: true
	// required: true
	// swagger:name shapeType
	ShapeType() string

	// swagger:name area
	Area() float64
}

// Polygon is a subtype of Shape AND a base of its own: it composes Shape as an
// allOf member and declares a second discriminator. An intermediate level is
// written as an interface, because only an interface can be embedded by the
// concrete structs below it.
//
// swagger:model
type Polygon interface {
	// swagger:allOf
	Shape

	// PolygonType selects the concrete polygon.
	//
	// discriminator: true
	// required: true
	// swagger:name polygonType
	PolygonType() string
}

// Square is a leaf, two levels down. It composes the INTERMEDIATE type, so it
// inherits Shape transitively.
//
// swagger:model
type Square struct {
	// swagger:allOf
	Polygon

	// Side is the length of a side.
	Side float64 `json:"side"`
}

{
  "description": "Polygon is a subtype of Shape AND a base of its own: it composes Shape as an\nallOf member and declares a second discriminator. An intermediate level is\nwritten as an interface, because only an interface can be embedded by the\nconcrete structs below it.",
  "allOf": [
    {
      "$ref": "#/definitions/Shape"
    },
    {
      "type": "object",
      "required": [
        "polygonType"
      ],
      "properties": {
        "polygonType": {
          "description": "PolygonType selects the concrete polygon.",
          "type": "string",
          "x-go-name": "PolygonType"
        }
      },
      "discriminator": "polygonType"
    }
  ],
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/polymorphism-nested"
}

// ListPetsParams is the parameter set for the listPets operation. Each field
// becomes one parameter; the operation IDs after swagger:parameters name the
// operations the set applies to.
//
// swagger:parameters listPets
type ListPetsParams struct {
	// Tag filters pets by tag.
	//
	// in: query
	Tag string `json:"tag"`

	// Limit caps the number of results.
	//
	// in: query
	// minimum: 1
	// maximum: 100
	Limit int32 `json:"limit"`
}

[
  {
    "type": "string",
    "x-go-name": "Tag",
    "description": "Tag filters pets by tag.",
    "name": "tag",
    "in": "query"
  },
  {
    "maximum": 100,
    "minimum": 1,
    "type": "integer",
    "format": "int32",
    "x-go-name": "Limit",
    "description": "Limit caps the number of results.",
    "name": "limit",
    "in": "query"
  }
]

// CreatePetParams is the request parameter set for createPet. A field marked
// `in: body` makes its Go type the request body schema — the usual shape for a
// POST or PUT payload.
//
// swagger:parameters createPet
type CreatePetParams struct {
	// Body is the pet to create.
	//
	// in: body
	// required: true
	Body Pet `json:"body"`
}

// swagger:route POST /pets/import pets createPet
//
// responses:
//
//	200: petsResponse

[
  {
    "x-go-name": "Body",
    "description": "Body is the pet to create.",
    "name": "body",
    "in": "body",
    "required": true,
    "schema": {
      "$ref": "#/definitions/Pet"
    }
  }
]

// Cursor is an opaque pagination token. As a struct it cannot be a query
// parameter on its own; swagger:type publishes it as a simple parameter.
type Cursor struct {
	Page  int
	Token string
}

// FilterPetsParams shows swagger:type on parameter fields: a struct-typed field
// is collapsed to a simple parameter. The override accepts a scalar or a
// []-wrapped scalar — the inline / type-name forms are rejected here (a
// non-body parameter has no schema to inline into).
//
// swagger:parameters filterPets
type FilterPetsParams struct {
	// After is an opaque cursor carried as a plain string query parameter.
	//
	// in: query
	// swagger:type string
	After Cursor `json:"after"`

	// Sort is a list of sort keys carried as an array-of-string query parameter.
	//
	// in: query
	// swagger:type []string
	Sort []Cursor `json:"sort"`
}

// swagger:route GET /pets/filter pets filterPets
//
// Filter pets with cursor pagination.
//
// responses:
//
//	200: description: matched pets

[
  {
    "type": "string",
    "x-go-name": "After",
    "description": "After is an opaque cursor carried as a plain string query parameter.",
    "name": "after",
    "in": "query"
  },
  {
    "type": "array",
    "items": {
      "type": "string"
    },
    "x-go-name": "Sort",
    "description": "Sort is a list of sort keys carried as an array-of-string query parameter.",
    "name": "sort",
    "in": "query"
  }
]

// PetsResponse is the list returned by listPets.
//
// swagger:response petsResponse
type PetsResponse struct {
	// in: body
	Body []Pet
}

// ErrorResponse is the default error payload.
//
// swagger:response errorResponse
type ErrorResponse struct {
	// in: body
	Body struct {
		// Message is a human-readable error message.
		Message string `json:"message"`
	}
}

{
  "description": "PetsResponse is the list returned by listPets.",
  "schema": {
    "type": "array",
    "items": {
      "$ref": "#/definitions/Pet"
    }
  }
}

// swagger:route POST /pets/{id}/photo pets uploadPetPhoto
//
// responses:
//
//	200: petsResponse

// UploadParams is the multipart upload for the uploadPetPhoto operation.
//
// swagger:parameters uploadPetPhoto
type UploadParams struct {
	// Photo is the image to upload.
	//
	// in: formData
	// swagger:file
	Photo io.ReadCloser `json:"photo"`
}

[
  {
    "type": "file",
    "x-go-name": "Photo",
    "description": "Photo is the image to upload.",
    "name": "photo",
    "in": "formData"
  }
]

// swagger:route GET /pets/search pets searchPets
//
// Searches pets. The operation links out to external documentation.
//
// externalDocs:
//   description: Search guide
//   url: https://example.com/docs/search
//
// responses:
//
//	200: petsResponse

// CatalogEntry carries externalDocs at the schema level (the link rides the
// definition) and on its fields. (On a simple-schema parameter externalDocs is
// dropped with a diagnostic: it is a full-Schema-only keyword.)
//
// externalDocs: {description: "Catalog schema reference", url: "https://example.com/docs/catalog"}
//
// swagger:model
type CatalogEntry struct {
	// SKU is the catalog identifier.
	SKU string `json:"sku"`

	// Vendor is a plain field: externalDocs attaches directly to the property.
	//
	// externalDocs: {description: "Vendor field docs", url: "https://example.com/docs/vendor"}
	Vendor string `json:"vendor"`

	// Supplier is a $ref'd field: its sibling externalDocs lifts onto the
	// field's allOf compound (a bare $ref cannot carry sibling keywords).
	//
	// externalDocs: {description: "Supplier docs", url: "https://example.com/docs/supplier"}
	Supplier Supplier `json:"supplier"`
}

// Supplier is referenced by CatalogEntry.Supplier.
//
// swagger:model
type Supplier struct {
	// Name is the supplier name.
	Name string `json:"name"`
}

{
  "description": "Search guide",
  "url": "https://example.com/docs/search"
}

// swagger:route GET /pets/search pets searchPets
//
// Searches pets. The operation links out to external documentation.
//
// externalDocs:
//   description: Search guide
//   url: https://example.com/docs/search
//
// responses:
//
//	200: petsResponse

// CatalogEntry carries externalDocs at the schema level (the link rides the
// definition) and on its fields. (On a simple-schema parameter externalDocs is
// dropped with a diagnostic: it is a full-Schema-only keyword.)
//
// externalDocs: {description: "Catalog schema reference", url: "https://example.com/docs/catalog"}
//
// swagger:model
type CatalogEntry struct {
	// SKU is the catalog identifier.
	SKU string `json:"sku"`

	// Vendor is a plain field: externalDocs attaches directly to the property.
	//
	// externalDocs: {description: "Vendor field docs", url: "https://example.com/docs/vendor"}
	Vendor string `json:"vendor"`

	// Supplier is a $ref'd field: its sibling externalDocs lifts onto the
	// field's allOf compound (a bare $ref cannot carry sibling keywords).
	//
	// externalDocs: {description: "Supplier docs", url: "https://example.com/docs/supplier"}
	Supplier Supplier `json:"supplier"`
}

// Supplier is referenced by CatalogEntry.Supplier.
//
// swagger:model
type Supplier struct {
	// Name is the supplier name.
	Name string `json:"name"`
}

{
  "description": "CatalogEntry carries externalDocs at the schema level (the link rides the\ndefinition) and on its fields. (On a simple-schema parameter externalDocs is\ndropped with a diagnostic: it is a full-Schema-only keyword.)",
  "type": "object",
  "properties": {
    "sku": {
      "description": "SKU is the catalog identifier.",
      "type": "string",
      "x-go-name": "SKU"
    },
    "supplier": {
      "description": "Supplier is a $ref'd field: its sibling externalDocs lifts onto the\nfield's allOf compound (a bare $ref cannot carry sibling keywords).",
      "allOf": [
        {
          "$ref": "#/definitions/Supplier"
        }
      ],
      "x-go-name": "Supplier",
      "externalDocs": {
        "description": "Supplier docs",
        "url": "https://example.com/docs/supplier"
      }
    },
    "vendor": {
      "description": "Vendor is a plain field: externalDocs attaches directly to the property.",
      "type": "string",
      "x-go-name": "Vendor",
      "externalDocs": {
        "description": "Vendor field docs",
        "url": "https://example.com/docs/vendor"
      }
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/routes",
  "externalDocs": {
    "description": "Catalog schema reference",
    "url": "https://example.com/docs/catalog"
  }
}