cmd/bpa-operator/vendor/github.com/go-openapi/spec/parameter.go

   1 // Copyright 2015 go-swagger maintainers
   2 //
   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
   6 //
   7 //    http://www.apache.org/licenses/LICENSE-2.0
   8 //
   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.
  14
  15 package spec
  16
  17 import (
  18         "encoding/json"
  19         "strings"
  20
  21         "github.com/go-openapi/jsonpointer"
  22         "github.com/go-openapi/swag"
  23 )
  24
  25 // QueryParam creates a query parameter
  26 func QueryParam(name string) *Parameter {
  27         return &Parameter{ParamProps: ParamProps{Name: name, In: "query"}}
  28 }
  29
  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}}
  33 }
  34
  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}}
  38 }
  39
  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"}}
  44 }
  45
  46 // FormDataParam creates a body parameter
  47 func FormDataParam(name string) *Parameter {
  48         return &Parameter{ParamProps: ParamProps{Name: name, In: "formData"}}
  49 }
  50
  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"}}
  55 }
  56
  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}}}}
  62 }
  63
  64 // ParamRef creates a parameter that's a json reference
  65 func ParamRef(uri string) *Parameter {
  66         p := new(Parameter)
  67         p.Ref = MustCreateRef(uri)
  68         return p
  69 }
  70
  71 // ParamProps describes the specific attributes of an operation parameter
  72 //
  73 // NOTE:
  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"`
  83 }
  84
  85 // Parameter a unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
  86 //
  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.
 109 //
 110 // For more information: http://goo.gl/8us55a#parameterObject
 111 type Parameter struct {
 112         Refable
 113         CommonValidations
 114         SimpleSchema
 115         VendorExtensible
 116         ParamProps
 117 }
 118
 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 {
 122                 return &ex, nil
 123         }
 124         if token == jsonRef {
 125                 return &p.Ref, nil
 126         }
 127
 128         r, _, err := jsonpointer.GetForToken(p.CommonValidations, token)
 129         if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {
 130                 return nil, err
 131         }
 132         if r != nil {
 133                 return r, nil
 134         }
 135         r, _, err = jsonpointer.GetForToken(p.SimpleSchema, token)
 136         if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {
 137                 return nil, err
 138         }
 139         if r != nil {
 140                 return r, nil
 141         }
 142         r, _, err = jsonpointer.GetForToken(p.ParamProps, token)
 143         return r, err
 144 }
 145
 146 // WithDescription a fluent builder method for the description of the parameter
 147 func (p *Parameter) WithDescription(description string) *Parameter {
 148         p.Description = description
 149         return p
 150 }
 151
 152 // Named a fluent builder method to override the name of the parameter
 153 func (p *Parameter) Named(name string) *Parameter {
 154         p.Name = name
 155         return p
 156 }
 157
 158 // WithLocation a fluent builder method to override the location of the parameter
 159 func (p *Parameter) WithLocation(in string) *Parameter {
 160         p.In = in
 161         return p
 162 }
 163
 164 // Typed a fluent builder method for the type of the parameter value
 165 func (p *Parameter) Typed(tpe, format string) *Parameter {
 166         p.Type = tpe
 167         p.Format = format
 168         return p
 169 }
 170
 171 // CollectionOf a fluent builder method for an array parameter
 172 func (p *Parameter) CollectionOf(items *Items, format string) *Parameter {
 173         p.Type = jsonArray
 174         p.Items = items
 175         p.CollectionFormat = format
 176         return p
 177 }
 178
 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
 183         return p
 184 }
 185
 186 // AllowsEmptyValues flags this parameter as being ok with empty values
 187 func (p *Parameter) AllowsEmptyValues() *Parameter {
 188         p.AllowEmptyValue = true
 189         return p
 190 }
 191
 192 // NoEmptyValues flags this parameter as not liking empty values
 193 func (p *Parameter) NoEmptyValues() *Parameter {
 194         p.AllowEmptyValue = false
 195         return p
 196 }
 197
 198 // AsOptional flags this parameter as optional
 199 func (p *Parameter) AsOptional() *Parameter {
 200         p.Required = false
 201         return p
 202 }
 203
 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
 207                 return p
 208         }
 209         p.Required = true
 210         return p
 211 }
 212
 213 // WithMaxLength sets a max length value
 214 func (p *Parameter) WithMaxLength(max int64) *Parameter {
 215         p.MaxLength = &max
 216         return p
 217 }
 218
 219 // WithMinLength sets a min length value
 220 func (p *Parameter) WithMinLength(min int64) *Parameter {
 221         p.MinLength = &min
 222         return p
 223 }
 224
 225 // WithPattern sets a pattern value
 226 func (p *Parameter) WithPattern(pattern string) *Parameter {
 227         p.Pattern = pattern
 228         return p
 229 }
 230
 231 // WithMultipleOf sets a multiple of value
 232 func (p *Parameter) WithMultipleOf(number float64) *Parameter {
 233         p.MultipleOf = &number
 234         return p
 235 }
 236
 237 // WithMaximum sets a maximum number value
 238 func (p *Parameter) WithMaximum(max float64, exclusive bool) *Parameter {
 239         p.Maximum = &max
 240         p.ExclusiveMaximum = exclusive
 241         return p
 242 }
 243
 244 // WithMinimum sets a minimum number value
 245 func (p *Parameter) WithMinimum(min float64, exclusive bool) *Parameter {
 246         p.Minimum = &min
 247         p.ExclusiveMinimum = exclusive
 248         return p
 249 }
 250
 251 // WithEnum sets a the enum values (replace)
 252 func (p *Parameter) WithEnum(values ...interface{}) *Parameter {
 253         p.Enum = append([]interface{}{}, values...)
 254         return p
 255 }
 256
 257 // WithMaxItems sets the max items
 258 func (p *Parameter) WithMaxItems(size int64) *Parameter {
 259         p.MaxItems = &size
 260         return p
 261 }
 262
 263 // WithMinItems sets the min items
 264 func (p *Parameter) WithMinItems(size int64) *Parameter {
 265         p.MinItems = &size
 266         return p
 267 }
 268
 269 // UniqueValues dictates that this array can only have unique items
 270 func (p *Parameter) UniqueValues() *Parameter {
 271         p.UniqueItems = true
 272         return p
 273 }
 274
 275 // AllowDuplicates this array can have duplicates
 276 func (p *Parameter) AllowDuplicates() *Parameter {
 277         p.UniqueItems = false
 278         return p
 279 }
 280
 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 {
 284                 return err
 285         }
 286         if err := json.Unmarshal(data, &p.Refable); err != nil {
 287                 return err
 288         }
 289         if err := json.Unmarshal(data, &p.SimpleSchema); err != nil {
 290                 return err
 291         }
 292         if err := json.Unmarshal(data, &p.VendorExtensible); err != nil {
 293                 return err
 294         }
 295         return json.Unmarshal(data, &p.ParamProps)
 296 }
 297
 298 // MarshalJSON converts this items object to JSON
 299 func (p Parameter) MarshalJSON() ([]byte, error) {
 300         b1, err := json.Marshal(p.CommonValidations)
 301         if err != nil {
 302                 return nil, err
 303         }
 304         b2, err := json.Marshal(p.SimpleSchema)
 305         if err != nil {
 306                 return nil, err
 307         }
 308         b3, err := json.Marshal(p.Refable)
 309         if err != nil {
 310                 return nil, err
 311         }
 312         b4, err := json.Marshal(p.VendorExtensible)
 313         if err != nil {
 314                 return nil, err
 315         }
 316         b5, err := json.Marshal(p.ParamProps)
 317         if err != nil {
 318                 return nil, err
 319         }
 320         return swag.ConcatJSON(b3, b1, b2, b4, b5), nil
 321 }