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 spec
16
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 p
68}
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, nil
122}
123if token == jsonRef {
124return &p.Ref, nil
125}
126
127r, _, err := jsonpointer.GetForToken(p.CommonValidations, token)
128if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {
129return nil, err
130}
131if r != nil {
132return r, nil
133}
134r, _, err = jsonpointer.GetForToken(p.SimpleSchema, token)
135if err != nil && !strings.HasPrefix(err.Error(), "object has no field") {
136return nil, err
137}
138if r != nil {
139return r, nil
140}
141r, _, err = jsonpointer.GetForToken(p.ParamProps, token)
142return r, err
143}
144
145// WithDescription a fluent builder method for the description of the parameter
146func (p *Parameter) WithDescription(description string) *Parameter {
147p.Description = description
148return p
149}
150
151// Named a fluent builder method to override the name of the parameter
152func (p *Parameter) Named(name string) *Parameter {
153p.Name = name
154return p
155}
156
157// WithLocation a fluent builder method to override the location of the parameter
158func (p *Parameter) WithLocation(in string) *Parameter {
159p.In = in
160return p
161}
162
163// Typed a fluent builder method for the type of the parameter value
164func (p *Parameter) Typed(tpe, format string) *Parameter {
165p.Type = tpe
166p.Format = format
167return p
168}
169
170// CollectionOf a fluent builder method for an array parameter
171func (p *Parameter) CollectionOf(items *Items, format string) *Parameter {
172p.Type = jsonArray
173p.Items = items
174p.CollectionFormat = format
175return p
176}
177
178// WithDefault sets the default value on this parameter
179func (p *Parameter) WithDefault(defaultValue interface{}) *Parameter {
180p.AsOptional() // with default implies optional
181p.Default = defaultValue
182return p
183}
184
185// AllowsEmptyValues flags this parameter as being ok with empty values
186func (p *Parameter) AllowsEmptyValues() *Parameter {
187p.AllowEmptyValue = true
188return p
189}
190
191// NoEmptyValues flags this parameter as not liking empty values
192func (p *Parameter) NoEmptyValues() *Parameter {
193p.AllowEmptyValue = false
194return p
195}
196
197// AsOptional flags this parameter as optional
198func (p *Parameter) AsOptional() *Parameter {
199p.Required = false
200return p
201}
202
203// AsRequired flags this parameter as required
204func (p *Parameter) AsRequired() *Parameter {
205if p.Default != nil { // with a default required makes no sense
206return p
207}
208p.Required = true
209return p
210}
211
212// WithMaxLength sets a max length value
213func (p *Parameter) WithMaxLength(max int64) *Parameter {
214p.MaxLength = &max
215return p
216}
217
218// WithMinLength sets a min length value
219func (p *Parameter) WithMinLength(min int64) *Parameter {
220p.MinLength = &min
221return p
222}
223
224// WithPattern sets a pattern value
225func (p *Parameter) WithPattern(pattern string) *Parameter {
226p.Pattern = pattern
227return p
228}
229
230// WithMultipleOf sets a multiple of value
231func (p *Parameter) WithMultipleOf(number float64) *Parameter {
232p.MultipleOf = &number
233return p
234}
235
236// WithMaximum sets a maximum number value
237func (p *Parameter) WithMaximum(max float64, exclusive bool) *Parameter {
238p.Maximum = &max
239p.ExclusiveMaximum = exclusive
240return p
241}
242
243// WithMinimum sets a minimum number value
244func (p *Parameter) WithMinimum(min float64, exclusive bool) *Parameter {
245p.Minimum = &min
246p.ExclusiveMinimum = exclusive
247return p
248}
249
250// WithEnum sets a the enum values (replace)
251func (p *Parameter) WithEnum(values ...interface{}) *Parameter {
252p.Enum = append([]interface{}{}, values...)
253return p
254}
255
256// WithMaxItems sets the max items
257func (p *Parameter) WithMaxItems(size int64) *Parameter {
258p.MaxItems = &size
259return p
260}
261
262// WithMinItems sets the min items
263func (p *Parameter) WithMinItems(size int64) *Parameter {
264p.MinItems = &size
265return p
266}
267
268// UniqueValues dictates that this array can only have unique items
269func (p *Parameter) UniqueValues() *Parameter {
270p.UniqueItems = true
271return p
272}
273
274// AllowDuplicates this array can have duplicates
275func (p *Parameter) AllowDuplicates() *Parameter {
276p.UniqueItems = false
277return p
278}
279
280// WithValidations is a fluent method to set parameter validations
281func (p *Parameter) WithValidations(val CommonValidations) *Parameter {
282p.SetValidations(SchemaValidations{CommonValidations: val})
283return p
284}
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 err
290}
291if err := json.Unmarshal(data, &p.Refable); err != nil {
292return err
293}
294if err := json.Unmarshal(data, &p.SimpleSchema); err != nil {
295return err
296}
297if err := json.Unmarshal(data, &p.VendorExtensible); err != nil {
298return err
299}
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, err
308}
309b2, err := json.Marshal(p.SimpleSchema)
310if err != nil {
311return nil, err
312}
313b3, err := json.Marshal(p.Refable)
314if err != nil {
315return nil, err
316}
317b4, err := json.Marshal(p.VendorExtensible)
318if err != nil {
319return nil, err
320}
321b5, err := json.Marshal(p.ParamProps)
322if err != nil {
323return nil, err
324}
325return swag.ConcatJSON(b3, b1, b2, b4, b5), nil
326}
327