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

     1  # swagger:model
     2  
     3  A **swagger:model** annotation optionally gets a model name as extra data on the line.
     4  when this appears anywhere in a comment for a struct, then that struct becomes a schema
     5  in the definitions object of swagger.
     6  
     7  <!--more-->
     8  
     9  The struct gets analyzed and all the collected models are added to the tree.
    10  The refs are tracked separately so that they can be renamed later on.
    11  
    12  Definitions only appear in the generated spec when they are actually used somewhere in the application (eg. on a params or response struct)
    13  
    14  ##### Syntax:
    15  
    16  ```
    17  swagger:model [?model name]
    18  ```
    19  
    20  ##### Properties:
    21  
    22  Annotation | Description
    23  -----------|------------
    24  **Maximum** | specifies the maximum a number or integer value can have
    25  **Minimum** | specifies the minimum a number or integer value can have
    26  **Multiple of** | specifies a value a number or integer value must be a multiple of
    27  **Minimum length** | the minimum length for a string value
    28  **Maximum length** | the maximum length for a string value
    29  **Pattern** | a regular expression a string value needs to match
    30  **Minimum items** | the minimum number of items a slice needs to have
    31  **Maximum items** | the maximum number of items a slice can have
    32  **Unique** | when set to true the slice can only contain unique items
    33  **Required** | when set to true this value needs to be set on the schema
    34  **Read Only** | when set to true this value will be marked as read-only and is not required in request bodies
    35  **Example** | an example value, parsed as the field's type<br/>(objects and slices are parsed as JSON)
    36  **Extensions** | list of extensions. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object.
    37  
    38  For slice properties there are also items to be defined. This might be a nested collection, for indicating nesting
    39  level the value is a 0-based index, so items.minLength is the same as items.0.minLength
    40  
    41  Annotation | Format
    42  -----------|--------
    43  **Items.*n*.Maximum** |  specifies the maximum a number or integer value can have at the level *n*
    44  **Items.*n*.Minimum** |  specifies the minimum a number or integer value can have at the level *n*
    45  **Items.*n*.Multiple of** | specifies a value a number or integer value must be a multiple of
    46  **Items.*n*.Minimum length** | the minimum length for a string value at the level *n*
    47  **Items.*n*.Maximum length** | the maximum length for a string value at the level *n*
    48  **Items.*n*.Pattern** | a regular expression a string value needs to match at the level *n*
    49  **Items.*n*.Minimum items** | the minimum number of items a slice needs to have at the level *n*
    50  **Items.*n*.Maximum items** | the maximum number of items a slice can have at the level *n*
    51  **Items.*n*.Unique** | when set to true the slice can only contain unique items at the level *n*
    52  
    53  ##### Example:
    54  
    55  ```go
    56  // User represents the user for this application
    57  //
    58  // A user is the security principal for this application.
    59  // It's also used as one of main axes for reporting.
    60  //
    61  // A user can have friends with whom they can share what they like.
    62  //
    63  // swagger:model
    64  type User struct {
    65  	// the id for this user
    66  	//
    67  	// required: true
    68  	// min: 1
    69  	ID int64 `json:"id"`
    70  
    71  	// the name for this user
    72  	// required: true
    73  	// min length: 3
    74  	Name string `json:"name"`
    75  
    76  	// the email address for this user
    77  	//
    78  	// required: true
    79  	// example: user@provider.net
    80  	Email strfmt.Email `json:"login"`
    81  
    82  	// the friends for this user
    83  	//
    84  	// Extensions:
    85  	// ---
    86  	// x-property-value: value
    87  	// x-property-array:
    88  	//   - value1
    89  	//   - value2
    90  	// x-property-array-obj:
    91  	//   - name: obj
    92  	//     value: field
    93  	// ---
    94  	Friends []User `json:"friends"`
    95  }
    96  ```
    97  
    98  ##### Result:
    99  
   100  ```yaml
   101  ---
   102  definitions:
   103    User:
   104      type: object
   105      title: User represents the user for this application
   106      description: "A user is the security principal for this application.\nIt's also used as one of the main axes for reporting.\n\nA user can have friends with whom they can share what they like."
   107      required:
   108        - id
   109        - name
   110        - login
   111      properties:
   112        id:
   113          description: the id for this user
   114          type: integer
   115          format: int64
   116          minimum: 1
   117        name:
   118          description: the name for this user
   119          type: string
   120          minLength: 3
   121        login:
   122          description: the email address for this user
   123          type: string
   124          format: email
   125          x-go-name: Email
   126          example: user@provider.net
   127        friends:
   128          description: the friends for this user
   129          type: array
   130          items:
   131            $ref: "#/definitions/User"
   132          x-property-value: value
   133          x-property-array:
   134            - value1
   135            - value2
   136          x-property-array-obj:
   137            - name: obj
   138              value: field
   139  ```