github.com/josephspurrier/go-swagger@v0.2.1-0.20221129144919-1f672a142a00/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  **Extensions** | a dictionary of custom [vendor extensions](https://swagger.io/docs/specification/2-0/swagger-extensions/); each key must start with `x-`
    44  
    45  For slice properties there are also items to be defined. This might be a nested collection, for indicating nesting
    46  level the value is a 0-based index, so items.minLength is the same as items.0.minLength
    47  
    48  Annotation | Format
    49  -----------|--------
    50  **Items.*n*.Maximum** |  specifies the maximum a number or integer value can have at the level *n*
    51  **Items.*n*.Minimum** |  specifies the minimum a number or integer value can have at the level *n*
    52  **Items.*n*.Multiple of** | specifies a value a number or integer value must be a multiple of
    53  **Items.*n*.Minimum length** | the minimum length for a string value at the level *n*
    54  **Items.*n*.Maximum length** | the maximum length for a string value at the level *n*
    55  **Items.*n*.Pattern** | a regular expression a string value needs to match at the level *n*
    56  **Items.*n*.Minimum items** | the minimum number of items a slice needs to have at the level *n*
    57  **Items.*n*.Maximum items** | the maximum number of items a slice can have at the level *n*
    58  **Items.*n*.Unique** | when set to true the slice can only contain unique items at the level *n*
    59  
    60  ##### Example:
    61  
    62  ```go
    63  // swagger:parameters listBars addBars
    64  type BarSliceParam struct {
    65  	// a BarSlice has bars which are strings
    66  	//
    67  	// min items: 3
    68  	// max items: 10
    69  	// unique: true
    70  	// items.minItems: 4
    71  	// items.maxItems: 9
    72  	// items.items.minItems: 5
    73  	// items.items.maxItems: 8
    74  	// items.items.items.minLength: 3
    75  	// items.items.items.maxLength: 10
    76  	// items.items.items.pattern: \w+
    77  	// collection format: pipe
    78  	// in: query
    79  	// example: [[["bar_000"]]]
    80    // Extensions:
    81    //   x-example-flag: true
    82    //   x-some-list:
    83    //     - dog
    84    //     - cat
    85    //     - bird
    86  	BarSlice [][][]string `json:"bar_slice"`
    87  }
    88  ```
    89  
    90  ##### Result:
    91  
    92  ```yaml
    93  ---
    94  operations:
    95    "/":
    96      get:
    97        operationId: listBars
    98        parameters:
    99          - name: bar_slice
   100            in: query
   101            maxItems: 10
   102            minItems: 3
   103            unique: true
   104            collectionFormat: pipe
   105            type: array
   106            example:
   107              - - - "bar_000"
   108            items:
   109              type: array
   110              maxItems: 9
   111              minItems: 4
   112              items:
   113                type: array
   114                maxItems: 8
   115                minItems: 5
   116                items:
   117                  type: string
   118                  minLength: 3
   119                  maxLength: 10
   120                  pattern: "\\w+"
   121            extensions:
   122              x-example-flag: true
   123              x-some-list:
   124                - dog
   125                - cat
   126                - bird
   127      post:
   128        operationId: addBars
   129        parameters:
   130          - name: bar_slice
   131            in: query
   132            maxItems: 10
   133            minItems: 3
   134            unique: true
   135            collectionFormat: pipe
   136            type: array
   137            example:
   138              - - - "bar_000"
   139            items:
   140              type: array
   141              maxItems: 9
   142              minItems: 4
   143              items:
   144                type: array
   145                maxItems: 8
   146                minItems: 5
   147                items:
   148                  type: string
   149                  minLength: 3
   150                  maxLength: 10
   151                  pattern: "\\w+"
   152            extensions:
   153              x-example-flag: true
   154              x-some-list:
   155                - dog
   156                - cat
   157                - bird
   158  ```