swagger:model

Usage

// swagger:model [<name>]   (where <name> overrides the definition name; defaults to the Go type name)

What it does

Declares a Go type as a published model.

The scanner walks the type, emits a schema into the spec’s definitions map, and resolves cross-references between models.

The title/description split follows a heuristic: a single-line comment ending in a period becomes the title. One without a trailing period becomes the description; a multi-line comment uses the first line as title and the rest as description.

The descriptive prose must come before the swagger:model line — an annotation-first block still publishes the model but drops its title and description.

Where it goes

On a type declaration (type T struct { … }, type T int, type T = Other, …).

Grammar (EBNF)

ModelAnnotation = ANN_MODEL , [ IDENT_NAME ] ;

The optional IDENT_NAME is the name the model takes in definitions (default: the Go type’s name). It must be a plain identifier (a JSON label), not a Go-qualified name — a dotted name such as utils.Error is rejected with a warning and dropped. Cross-package types resolve automatically, so reference a model by its bare name.

The annotation opens a SchemaBlock body — its fields and their doc comments carry the schema validations.

Supported keywords

Every schema decorator and validation keyword is accepted on a field doc comment. A keyword that is not compatible with the field’s inferred schema type (e.g. minLength on an integer) is ignored and raises a diagnostic.

Example

The doc comment above the type drives the model’s name, title and description:

// Pet is the petstore's primary entity.            <- title (first line, ends with a period)
//
// A pet can be any little animal you care about.   <- description
// In this example the model name is inferred from the type name, here "Pet".
//
// 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"`
}

Pass an argument to override the name; the type is then published as #/definitions/PetWithExtras:

// swagger:model PetWithExtras
type DetailedPet struct { … }

A single field group declaring several names emits one property per name. A json: tag on the group cannot rename the individual fields — each keeps its own name — though tag options still apply:

// Color is an RGBA colour. A single field group declaring several names emits
// one property per name — R, G, B and A each become their own integer property.
// A json tag on the group cannot rename the individual fields (each keeps its
// own name), though tag options such as omitempty still apply.
//
// swagger:model
type Color struct {
	R, G, B, A uint8 `json:",omitempty"`
}

{
  "description": "Color is an RGBA colour. A single field group declaring several names emits\none property per name — R, G, B and A each become their own integer property.\nA json tag on the group cannot rename the individual fields (each keeps its\nown name), though tag options such as omitempty still apply.",
  "type": "object",
  "properties": {
    "A": {
      "type": "integer",
      "format": "uint8"
    },
    "B": {
      "type": "integer",
      "format": "uint8"
    },
    "G": {
      "type": "integer",
      "format": "uint8"
    },
    "R": {
      "type": "integer",
      "format": "uint8"
    }
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/models"
}

Full example. fixtures/enhancements/named-struct-tags-ref/types.go.