github.com/ryanbennettvoid/go-swagger@v0.18.1-0.20190104015444-3854bbbe2392/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  
    37  For slice properties there are also items to be defined. This might be a nested collection, for indicating nesting
    38  level the value is a 0-based index, so items.minLength is the same as items.0.minLength
    39  
    40  Annotation | Format
    41  -----------|--------
    42  **Items.*n*.Maximum** |  specifies the maximum a number or integer value can have at the level *n*
    43  **Items.*n*.Minimum** |  specifies the minimum a number or integer value can have at the level *n*
    44  **Items.*n*.Multiple of** | specifies a value a number or integer value must be a multiple of
    45  **Items.*n*.Minimum length** | the minimum length for a string value at the level *n*
    46  **Items.*n*.Maximum length** | the maximum length for a string value at the level *n*
    47  **Items.*n*.Pattern** | a regular expression a string value needs to match at the level *n*
    48  **Items.*n*.Minimum items** | the minimum number of items a slice needs to have at the level *n*
    49  **Items.*n*.Maximum items** | the maximum number of items a slice can have at the level *n*
    50  **Items.*n*.Unique** | when set to true the slice can only contain unique items at the level *n*
    51  
    52  ##### Example:
    53  
    54  ```go
    55  // User represents the user for this application
    56  //
    57  // A user is the security principal for this application.
    58  // It's also used as one of main axes for reporting.
    59  //
    60  // A user can have friends with whom they can share what they like.
    61  //
    62  // swagger:model
    63  type User struct {
    64  	// the id for this user
    65  	//
    66  	// required: true
    67  	// min: 1
    68  	ID int64 `json:"id"`
    69  
    70  	// the name for this user
    71  	// required: true
    72  	// min length: 3
    73  	Name string `json:"name"`
    74  
    75  	// the email address for this user
    76  	//
    77  	// required: true
    78  	// example: user@provider.net
    79  	Email strfmt.Email `json:"login"`
    80  
    81  	// the friends for this user
    82  	Friends []User `json:"friends"`
    83  }
    84  ```
    85  
    86  ##### Result:
    87  
    88  ```yaml
    89  ---
    90  definitions:
    91    User:
    92      type: object
    93      title: User represents the user for this application
    94      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."
    95      required:
    96        - id
    97        - name
    98        - login
    99      properties:
   100        id:
   101          description: the id for this user
   102          type: integer
   103          format: int64
   104          minimum: 1
   105        name:
   106          description: the name for this user
   107          type: string
   108          minLength: 3
   109        login:
   110          description: the email address for this user
   111          type: string
   112          format: email
   113          x-go-name: Email
   114          example: user@provider.net
   115        friends:
   116          description: the friends for this user
   117          type: array
   118          items:
   119            $ref: "#/definitions/User"
   120  ```