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 ```