1 // Copyright 2015 go-swagger maintainers
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
21 "github.com/go-openapi/jsonpointer"
22 "github.com/go-openapi/swag"
25 // QueryParam creates a query parameter
26 func QueryParam(name string) *Parameter {
27 return &Parameter{ParamProps: ParamProps{Name: name, In: "query"}}
30 // HeaderParam creates a header parameter, this is always required by default
31 func HeaderParam(name string) *Parameter {
32 return &Parameter{ParamProps: ParamProps{Name: name, In: "header", Required: true}}
35 // PathParam creates a path parameter, this is always required
36 func PathParam(name string) *Parameter {
37 return &Parameter{ParamProps: ParamProps{Name: name, In: "path", Required: true}}
40 // BodyParam creates a body parameter
41 func BodyParam(name string, schema *Schema) *Parameter {
42 return &Parameter{ParamProps: ParamProps{Name: name, In: "body", Schema: schema},
43 SimpleSchema: SimpleSchema{Type: "object"}}
46 // FormDataParam creates a body parameter
47 func FormDataParam(name string) *Parameter {
48 return &Parameter{ParamProps: ParamProps{Name: name, In: "formData"}}
51 // FileParam creates a body parameter
52 func FileParam(name string) *Parameter {
53 return &Parameter{ParamProps: ParamProps{Name: name, In: "formData"},
54 SimpleSchema: SimpleSchema{Type: "file"}}
57 // SimpleArrayParam creates a param for a simple array (string, int, date etc)
58 func SimpleArrayParam(name, tpe, fmt string) *Parameter {
59 return &Parameter{ParamProps: ParamProps{Name: name},
60 SimpleSchema: SimpleSchema{Type: jsonArray, CollectionFormat: "csv",
61 Items: &Items{SimpleSchema: SimpleSchema{Type: "string", Format: fmt}}}}
64 // ParamRef creates a parameter that's a json reference
65 func ParamRef(uri string) *Parameter {
67 p.Ref = MustCreateRef(uri)
71 // ParamProps describes the specific attributes of an operation parameter
74 // - Schema is defined when "in" == "body": see validate
75 // - AllowEmptyValue is allowed where "in" == "query" || "formData"
76 type ParamProps struct {
77 Description string `json:"description,omitempty"`
78 Name string `json:"name,omitempty"`
79 In string `json:"in,omitempty"`
80 Required bool `json:"required,omitempty"`
81 Schema *Schema `json:"schema,omitempty"`
82 AllowEmptyValue bool `json:"allowEmptyValue,omitempty"`
85 // Parameter a unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
87 // There are five possible parameter types.
88 // * Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part
89 // of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`,
90 // the path parameter is `itemId`.
91 // * Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
92 // * Header - Custom headers that are expected as part of the request.
93 // * Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be
94 // _one_ body parameter. The name of the body parameter has no effect on the parameter itself and is used for
95 // documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist
96 // together for the same operation.
97 // * Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded` or
98 // `multipart/form-data` are used as the content type of the request (in Swagger's definition,
99 // the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used
100 // to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be
101 // declared together with a body parameter for the same operation. Form parameters have a different format based on
102 // the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4).
103 // * `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload.
104 // For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple
105 // parameters that are being transferred.
106 // * `multipart/form-data` - each parameter takes a section in the payload with an internal header.
107 // For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is
108 // `submit-name`. This type of form parameters is more commonly used for file transfers.
110 // For more information: http://goo.gl/8us55a#parameterObject
111 type Parameter struct {
119 // JSONLookup look up a value by the json property name
120 func (p Parameter) JSONLookup(token string) (interface{}, error) {
121 if ex, ok := p.Extensions[token]; ok {
124 if token == jsonRef {
128 r, _, err := jsonpointer.GetForToken(p.CommonValidations, token)
129 if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {
135 r, _, err = jsonpointer.GetForToken(p.SimpleSchema, token)
136 if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {
142 r, _, err = jsonpointer.GetForToken(p.ParamProps, token)
146 // WithDescription a fluent builder method for the description of the parameter
147 func (p *Parameter) WithDescription(description string) *Parameter {
148 p.Description = description
152 // Named a fluent builder method to override the name of the parameter
153 func (p *Parameter) Named(name string) *Parameter {
158 // WithLocation a fluent builder method to override the location of the parameter
159 func (p *Parameter) WithLocation(in string) *Parameter {
164 // Typed a fluent builder method for the type of the parameter value
165 func (p *Parameter) Typed(tpe, format string) *Parameter {
171 // CollectionOf a fluent builder method for an array parameter
172 func (p *Parameter) CollectionOf(items *Items, format string) *Parameter {
175 p.CollectionFormat = format
179 // WithDefault sets the default value on this parameter
180 func (p *Parameter) WithDefault(defaultValue interface{}) *Parameter {
181 p.AsOptional() // with default implies optional
182 p.Default = defaultValue
186 // AllowsEmptyValues flags this parameter as being ok with empty values
187 func (p *Parameter) AllowsEmptyValues() *Parameter {
188 p.AllowEmptyValue = true
192 // NoEmptyValues flags this parameter as not liking empty values
193 func (p *Parameter) NoEmptyValues() *Parameter {
194 p.AllowEmptyValue = false
198 // AsOptional flags this parameter as optional
199 func (p *Parameter) AsOptional() *Parameter {
204 // AsRequired flags this parameter as required
205 func (p *Parameter) AsRequired() *Parameter {
206 if p.Default != nil { // with a default required makes no sense
213 // WithMaxLength sets a max length value
214 func (p *Parameter) WithMaxLength(max int64) *Parameter {
219 // WithMinLength sets a min length value
220 func (p *Parameter) WithMinLength(min int64) *Parameter {
225 // WithPattern sets a pattern value
226 func (p *Parameter) WithPattern(pattern string) *Parameter {
231 // WithMultipleOf sets a multiple of value
232 func (p *Parameter) WithMultipleOf(number float64) *Parameter {
233 p.MultipleOf = &number
237 // WithMaximum sets a maximum number value
238 func (p *Parameter) WithMaximum(max float64, exclusive bool) *Parameter {
240 p.ExclusiveMaximum = exclusive
244 // WithMinimum sets a minimum number value
245 func (p *Parameter) WithMinimum(min float64, exclusive bool) *Parameter {
247 p.ExclusiveMinimum = exclusive
251 // WithEnum sets a the enum values (replace)
252 func (p *Parameter) WithEnum(values ...interface{}) *Parameter {
253 p.Enum = append([]interface{}{}, values...)
257 // WithMaxItems sets the max items
258 func (p *Parameter) WithMaxItems(size int64) *Parameter {
263 // WithMinItems sets the min items
264 func (p *Parameter) WithMinItems(size int64) *Parameter {
269 // UniqueValues dictates that this array can only have unique items
270 func (p *Parameter) UniqueValues() *Parameter {
275 // AllowDuplicates this array can have duplicates
276 func (p *Parameter) AllowDuplicates() *Parameter {
277 p.UniqueItems = false
281 // UnmarshalJSON hydrates this items instance with the data from JSON
282 func (p *Parameter) UnmarshalJSON(data []byte) error {
283 if err := json.Unmarshal(data, &p.CommonValidations); err != nil {
286 if err := json.Unmarshal(data, &p.Refable); err != nil {
289 if err := json.Unmarshal(data, &p.SimpleSchema); err != nil {
292 if err := json.Unmarshal(data, &p.VendorExtensible); err != nil {
295 return json.Unmarshal(data, &p.ParamProps)
298 // MarshalJSON converts this items object to JSON
299 func (p Parameter) MarshalJSON() ([]byte, error) {
300 b1, err := json.Marshal(p.CommonValidations)
304 b2, err := json.Marshal(p.SimpleSchema)
308 b3, err := json.Marshal(p.Refable)
312 b4, err := json.Marshal(p.VendorExtensible)
316 b5, err := json.Marshal(p.ParamProps)
320 return swag.ConcatJSON(b3, b1, b2, b4, b5), nil