podman
326 строк · 10.3 Кб
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
15package spec16
17import (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
26func QueryParam(name string) *Parameter {27return &Parameter{ParamProps: ParamProps{Name: name, In: "query"}}28}
29
30// HeaderParam creates a header parameter, this is always required by default
31func HeaderParam(name string) *Parameter {32return &Parameter{ParamProps: ParamProps{Name: name, In: "header", Required: true}}33}
34
35// PathParam creates a path parameter, this is always required
36func PathParam(name string) *Parameter {37return &Parameter{ParamProps: ParamProps{Name: name, In: "path", Required: true}}38}
39
40// BodyParam creates a body parameter
41func BodyParam(name string, schema *Schema) *Parameter {42return &Parameter{ParamProps: ParamProps{Name: name, In: "body", Schema: schema}}43}
44
45// FormDataParam creates a body parameter
46func FormDataParam(name string) *Parameter {47return &Parameter{ParamProps: ParamProps{Name: name, In: "formData"}}48}
49
50// FileParam creates a body parameter
51func FileParam(name string) *Parameter {52return &Parameter{ParamProps: ParamProps{Name: name, In: "formData"},53SimpleSchema: SimpleSchema{Type: "file"}}54}
55
56// SimpleArrayParam creates a param for a simple array (string, int, date etc)
57func SimpleArrayParam(name, tpe, fmt string) *Parameter {58return &Parameter{ParamProps: ParamProps{Name: name},59SimpleSchema: SimpleSchema{Type: jsonArray, CollectionFormat: "csv",60Items: &Items{SimpleSchema: SimpleSchema{Type: tpe, Format: fmt}}}}61}
62
63// ParamRef creates a parameter that's a json reference
64func ParamRef(uri string) *Parameter {65p := new(Parameter)66p.Ref = MustCreateRef(uri)67return p68}
69
70// ParamProps describes the specific attributes of an operation parameter
71//
72// NOTE:
73// - Schema is defined when "in" == "body": see validate
74// - AllowEmptyValue is allowed where "in" == "query" || "formData"
75type ParamProps struct {76Description string `json:"description,omitempty"`77Name string `json:"name,omitempty"`78In string `json:"in,omitempty"`79Required bool `json:"required,omitempty"`80Schema *Schema `json:"schema,omitempty"`81AllowEmptyValue bool `json:"allowEmptyValue,omitempty"`82}
83
84// Parameter a unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
85//
86// There are five possible parameter types.
87// * Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part
88// of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`,
89// the path parameter is `itemId`.
90// * Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
91// * Header - Custom headers that are expected as part of the request.
92// * Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be
93// _one_ body parameter. The name of the body parameter has no effect on the parameter itself and is used for
94// documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist
95// together for the same operation.
96// * Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded` or
97// `multipart/form-data` are used as the content type of the request (in Swagger's definition,
98// the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used
99// to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be
100// declared together with a body parameter for the same operation. Form parameters have a different format based on
101// the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4).
102// * `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload.
103// For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple
104// parameters that are being transferred.
105// * `multipart/form-data` - each parameter takes a section in the payload with an internal header.
106// For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is
107// `submit-name`. This type of form parameters is more commonly used for file transfers.
108//
109// For more information: http://goo.gl/8us55a#parameterObject
110type Parameter struct {111Refable
112CommonValidations
113SimpleSchema
114VendorExtensible
115ParamProps
116}
117
118// JSONLookup look up a value by the json property name
119func (p Parameter) JSONLookup(token string) (interface{}, error) {120if ex, ok := p.Extensions[token]; ok {121return &ex, nil122}123if token == jsonRef {124return &p.Ref, nil125}126
127r, _, err := jsonpointer.GetForToken(p.CommonValidations, token)128if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {129return nil, err130}131if r != nil {132return r, nil133}134r, _, err = jsonpointer.GetForToken(p.SimpleSchema, token)135if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {136return nil, err137}138if r != nil {139return r, nil140}141r, _, err = jsonpointer.GetForToken(p.ParamProps, token)142return r, err143}
144
145// WithDescription a fluent builder method for the description of the parameter
146func (p *Parameter) WithDescription(description string) *Parameter {147p.Description = description148return p149}
150
151// Named a fluent builder method to override the name of the parameter
152func (p *Parameter) Named(name string) *Parameter {153p.Name = name154return p155}
156
157// WithLocation a fluent builder method to override the location of the parameter
158func (p *Parameter) WithLocation(in string) *Parameter {159p.In = in160return p161}
162
163// Typed a fluent builder method for the type of the parameter value
164func (p *Parameter) Typed(tpe, format string) *Parameter {165p.Type = tpe166p.Format = format167return p168}
169
170// CollectionOf a fluent builder method for an array parameter
171func (p *Parameter) CollectionOf(items *Items, format string) *Parameter {172p.Type = jsonArray173p.Items = items174p.CollectionFormat = format175return p176}
177
178// WithDefault sets the default value on this parameter
179func (p *Parameter) WithDefault(defaultValue interface{}) *Parameter {180p.AsOptional() // with default implies optional181p.Default = defaultValue182return p183}
184
185// AllowsEmptyValues flags this parameter as being ok with empty values
186func (p *Parameter) AllowsEmptyValues() *Parameter {187p.AllowEmptyValue = true188return p189}
190
191// NoEmptyValues flags this parameter as not liking empty values
192func (p *Parameter) NoEmptyValues() *Parameter {193p.AllowEmptyValue = false194return p195}
196
197// AsOptional flags this parameter as optional
198func (p *Parameter) AsOptional() *Parameter {199p.Required = false200return p201}
202
203// AsRequired flags this parameter as required
204func (p *Parameter) AsRequired() *Parameter {205if p.Default != nil { // with a default required makes no sense206return p207}208p.Required = true209return p210}
211
212// WithMaxLength sets a max length value
213func (p *Parameter) WithMaxLength(max int64) *Parameter {214p.MaxLength = &max215return p216}
217
218// WithMinLength sets a min length value
219func (p *Parameter) WithMinLength(min int64) *Parameter {220p.MinLength = &min221return p222}
223
224// WithPattern sets a pattern value
225func (p *Parameter) WithPattern(pattern string) *Parameter {226p.Pattern = pattern227return p228}
229
230// WithMultipleOf sets a multiple of value
231func (p *Parameter) WithMultipleOf(number float64) *Parameter {232p.MultipleOf = &number233return p234}
235
236// WithMaximum sets a maximum number value
237func (p *Parameter) WithMaximum(max float64, exclusive bool) *Parameter {238p.Maximum = &max239p.ExclusiveMaximum = exclusive240return p241}
242
243// WithMinimum sets a minimum number value
244func (p *Parameter) WithMinimum(min float64, exclusive bool) *Parameter {245p.Minimum = &min246p.ExclusiveMinimum = exclusive247return p248}
249
250// WithEnum sets a the enum values (replace)
251func (p *Parameter) WithEnum(values ...interface{}) *Parameter {252p.Enum = append([]interface{}{}, values...)253return p254}
255
256// WithMaxItems sets the max items
257func (p *Parameter) WithMaxItems(size int64) *Parameter {258p.MaxItems = &size259return p260}
261
262// WithMinItems sets the min items
263func (p *Parameter) WithMinItems(size int64) *Parameter {264p.MinItems = &size265return p266}
267
268// UniqueValues dictates that this array can only have unique items
269func (p *Parameter) UniqueValues() *Parameter {270p.UniqueItems = true271return p272}
273
274// AllowDuplicates this array can have duplicates
275func (p *Parameter) AllowDuplicates() *Parameter {276p.UniqueItems = false277return p278}
279
280// WithValidations is a fluent method to set parameter validations
281func (p *Parameter) WithValidations(val CommonValidations) *Parameter {282p.SetValidations(SchemaValidations{CommonValidations: val})283return p284}
285
286// UnmarshalJSON hydrates this items instance with the data from JSON
287func (p *Parameter) UnmarshalJSON(data []byte) error {288if err := json.Unmarshal(data, &p.CommonValidations); err != nil {289return err290}291if err := json.Unmarshal(data, &p.Refable); err != nil {292return err293}294if err := json.Unmarshal(data, &p.SimpleSchema); err != nil {295return err296}297if err := json.Unmarshal(data, &p.VendorExtensible); err != nil {298return err299}300return json.Unmarshal(data, &p.ParamProps)301}
302
303// MarshalJSON converts this items object to JSON
304func (p Parameter) MarshalJSON() ([]byte, error) {305b1, err := json.Marshal(p.CommonValidations)306if err != nil {307return nil, err308}309b2, err := json.Marshal(p.SimpleSchema)310if err != nil {311return nil, err312}313b3, err := json.Marshal(p.Refable)314if err != nil {315return nil, err316}317b4, err := json.Marshal(p.VendorExtensible)318if err != nil {319return nil, err320}321b5, err := json.Marshal(p.ParamProps)322if err != nil {323return nil, err324}325return swag.ConcatJSON(b3, b1, b2, b4, b5), nil326}
327