github.com/AngusLu/go-swagger@v0.28.0/docs/use/spec/discriminated.md (about)

     1  # swagger:discriminated
     2  
     3  Marks an embedded type as  a member for allOf and sets the x-class value. On interface definitions there is another annotation on methods allowed _swagger:name_
     4  
     5  <!--more-->
     6  
     7  The swagger:allOf annotation can be followed by a string. This string will be the value for the `x-class` vendor extension. This value is used as constant for the discriminator field.
     8  
     9  An interface that is embedded expects to have 1 method that is commented with `Discriminator: true`. That field will be used as discriminator field when marshalling/unmarshalling objects.
    10  
    11  Because this is for use with interfaces we can't make use of the json struct tag to allow for spec name overriding. So instead you can annotate method names on an interface with swagger:name and a value this will then provide the json field name.
    12  
    13  ##### Syntax:
    14  
    15  ```
    16  swagger:allOf org.example.something.TypeName
    17  ```
    18  
    19  ##### Example:
    20  
    21  ```go
    22  // TeslaCar is a tesla car
    23  //
    24  // swagger:model
    25  type TeslaCar interface {
    26  	// The model of tesla car
    27  	//
    28  	// discriminator: true
    29  	// swagger:name model
    30  	Model() string
    31  
    32  	// AutoPilot returns true when it supports autopilot
    33  	// swagger:name autoPilot
    34  	AutoPilot() bool
    35  }
    36  
    37  // The ModelS version of the tesla car
    38  //
    39  // swagger:model modelS
    40  type ModelS struct {
    41  	// swagger:allOf com.tesla.models.ModelS
    42  	TeslaCar
    43  	// The edition of this Model S
    44  	Edition string `json:"edition"`
    45  }
    46  
    47  // The ModelX version of the tesla car
    48  //
    49  // swagger:model modelX
    50  type ModelX struct {
    51  	// swagger:allOf com.tesla.models.ModelX
    52  	TeslaCar
    53  	// The number of doors on this Model X
    54  	Doors int32 `json:"doors"`
    55  }
    56  ```
    57  
    58  ##### Result:
    59  
    60  ```yaml
    61  ---
    62  definitions:
    63    TeslaCar:
    64      title: TeslaCar is a tesla car
    65      type: object
    66      discriminator: "model"
    67      properties:
    68        model:
    69          description: The model of tesla car
    70          type: string
    71          x-go-name: Model
    72        autoPilot:
    73          description: AutoPilot returns true when it supports autopilot
    74          type: integer
    75          format: int32
    76          x-go-name: AutoPilot
    77    modelS:
    78      allOf:
    79        - $ref: "#/definitions/TeslaCar"
    80        - title: The ModelS version of the tesla car
    81          properties:
    82            edition:
    83              description: "The edition of this model S"
    84              type: string
    85              x-go-name: Edition
    86      x-class: "com.tesla.models.ModelS"
    87      x-go-name: "ModelX"
    88    modelX:
    89      allOf:
    90        - $ref: "#/definitions/TeslaCar"
    91        - title: The ModelX version of the tesla car
    92          properties:
    93            doors:
    94              description: "The number of doors on this Model X"
    95              type: integer
    96              format: int32
    97              x-go-name: Doors
    98      x-class: "com.tesla.models.ModelX"
    99      x-go-name: ModelX
   100  ```