swagger:allOf

Usage

// swagger:allOf

What it does

Marks a struct as participating in an allOf composition.

The struct’s fields plus any embedded swagger:model-tagged base produce an allOf: [$ref base, {inline fields}] schema. The companion convention is to embed the base type as an anonymous field with this annotation on the embedding’s doc comment (or on the embedded type itself).

Where it goes

On a struct field that embeds another type, or on a struct type that has at least one embedded base.

Grammar (EBNF)

AllOfBlock = ANN_ALLOF , [ Title ] , [ Description ] ;

The annotation takes no arguments; an optional title/description may follow on the doc comment.

Supported keywords

Schema-context keywords on the inline-object member (the second allOf element).

Example

A struct embedding a swagger:model base with swagger:allOf on the embed produces an allOf of the base $ref and an inline-object member carrying the embedding struct’s own fields:

Annotated Go

// 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"`
}

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

Generated spec

{
  "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"
}

Full source: docs/examples/concepts/models/testdata/allof.json

The same composition applies when the embedding struct is a swagger:response body: the embedded base emits an allOf: [{$ref}, …] arm only when it is a swagger:model (a definition exists to point at); an embedded swagger:response has its fields inlined instead.

Full example. fixtures/enhancements/allof-edges/types.go.