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

     1  # swagger:parameters
     2  
     3  The **swagger:parameters** annotation links a struct to one or more operations. The parameters in the resulting swagger spec can be composed of several structs.
     4  There are no guarantees given on how property name overlaps are resolved when several structs apply to the same operation.
     5  This tag works very similarly to the swagger:model tag except that it produces valid parameter objects instead of schema
     6  objects.
     7  <!--more-->
     8  When this appears anywhere in a comment for a struct, then that struct becomes a schema
     9  in the definitions object of swagger.
    10  
    11  The struct gets analyzed and all the collected models are added to the tree.
    12  The refs are tracked separately so that they can be renamed later on.
    13  
    14  At this moment the parameters require one or more structs to be defined, it's not possible to annotate plain var
    15  entries at this moment.
    16  
    17  ##### Syntax:
    18  
    19  ```
    20  swagger:parameters [operationid1 operationid2]
    21  ```
    22  
    23  ##### Properties:
    24  
    25  The fields of this struct can be decorated with a number of annotations. For the field name it uses the struct field
    26  name, it respects the json struct field tag for customizing the name.
    27  
    28  Annotation | Format
    29  ---------- | ------
    30  **In** | where to find the parameter
    31  **Collection Format** | when a slice the formatter for the collection when serialized on the request
    32  **Maximum** | specifies the maximum a number or integer value can have
    33  **Minimum** | specifies the minimum a number or integer value can have
    34  **Multiple of** | specifies a value a number or integer value must be a multiple of
    35  **Minimum length** | the minimum length for a string value
    36  **Maximum length** | the maximum length for a string value
    37  **Pattern** | a regular expression a string value needs to match
    38  **Minimum items** | the minimum number of items a slice needs to have
    39  **Maximum items** | the maximum number of items a slice can have
    40  **Unique** | when set to true the slice can only contain unique items
    41  **Required** | when set to true this value needs to be present in the request
    42  **Example** | an example value, parsed as the field's type<br/>(objects and slices are parsed as JSON)
    43  
    44  For slice properties there are also items to be defined. This might be a nested collection, for indicating nesting
    45  level the value is a 0-based index, so items.minLength is the same as items.0.minLength
    46  
    47  Annotation | Format
    48  -----------|--------
    49  **Items.*n*.Maximum** |  specifies the maximum a number or integer value can have at the level *n*
    50  **Items.*n*.Minimum** |  specifies the minimum a number or integer value can have at the level *n*
    51  **Items.*n*.Multiple of** | specifies a value a number or integer value must be a multiple of
    52  **Items.*n*.Minimum length** | the minimum length for a string value at the level *n*
    53  **Items.*n*.Maximum length** | the maximum length for a string value at the level *n*
    54  **Items.*n*.Pattern** | a regular expression a string value needs to match at the level *n*
    55  **Items.*n*.Minimum items** | the minimum number of items a slice needs to have at the level *n*
    56  **Items.*n*.Maximum items** | the maximum number of items a slice can have at the level *n*
    57  **Items.*n*.Unique** | when set to true the slice can only contain unique items at the level *n*
    58  
    59  ##### Example:
    60  
    61  ```go
    62  // swagger:parameters listBars addBars
    63  type BarSliceParam struct {
    64  	// a BarSlice has bars which are strings
    65  	//
    66  	// min items: 3
    67  	// max items: 10
    68  	// unique: true
    69  	// items.minItems: 4
    70  	// items.maxItems: 9
    71  	// items.items.minItems: 5
    72  	// items.items.maxItems: 8
    73  	// items.items.items.minLength: 3
    74  	// items.items.items.maxLength: 10
    75  	// items.items.items.pattern: \w+
    76  	// collection format: pipe
    77  	// in: query
    78  	// example: [[["bar_000"]]]
    79  	BarSlice [][][]string `json:"bar_slice"`
    80  }
    81  ```
    82  
    83  ##### Result:
    84  
    85  ```yaml
    86  ---
    87  operations:
    88    "/":
    89      get:
    90        operationId: listBars
    91        parameters:
    92          - name: bar_slice
    93            in: query
    94            maxItems: 10
    95            minItems: 3
    96            unique: true
    97            collectionFormat: pipe
    98            type: array
    99            example:
   100              - - - "bar_000"
   101            items:
   102              type: array
   103              maxItems: 9
   104              minItems: 4
   105              items:
   106                type: array
   107                maxItems: 8
   108                minItems: 5
   109                items:
   110                  type: string
   111                  minLength: 3
   112                  maxLength: 10
   113                  pattern: "\\w+"
   114      post:
   115        operationId: addBars
   116        parameters:
   117          - name: bar_slice
   118            in: query
   119            maxItems: 10
   120            minItems: 3
   121            unique: true
   122            collectionFormat: pipe
   123            type: array
   124            example:
   125              - - - "bar_000"
   126            items:
   127              type: array
   128              maxItems: 9
   129              minItems: 4
   130              items:
   131                type: array
   132                maxItems: 8
   133                minItems: 5
   134                items:
   135                  type: string
   136                  minLength: 3
   137                  maxLength: 10
   138                  pattern: "\\w+"
   139  ```