001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.camel.model.rest;
018
019import java.util.ArrayList;
020import java.util.Arrays;
021import java.util.List;
022import javax.xml.bind.annotation.XmlAccessType;
023import javax.xml.bind.annotation.XmlAccessorType;
024import javax.xml.bind.annotation.XmlAttribute;
025import javax.xml.bind.annotation.XmlElement;
026import javax.xml.bind.annotation.XmlElementWrapper;
027import javax.xml.bind.annotation.XmlRootElement;
028import javax.xml.bind.annotation.XmlTransient;
029
030import org.apache.camel.spi.Metadata;
031import org.apache.camel.util.StringHelper;
032
033/**
034 * To specify the rest operation parameters using Swagger.
035 * <p/>
036 * This maps to the Swagger Parameter Message Object.
037 */
038@Metadata(label = "rest")
039@XmlRootElement(name = "param")
040@XmlAccessorType(XmlAccessType.FIELD)
041public class RestOperationParamDefinition {
042
043    @XmlTransient
044    private VerbDefinition verb;
045
046    @XmlAttribute(required = true)
047    private String name;
048
049    @XmlAttribute(required = true)
050    @Metadata(defaultValue = "path")
051    private RestParamType type;
052
053    @XmlAttribute
054    @Metadata(defaultValue = "")
055    private String description;
056
057    @XmlAttribute
058    @Metadata(defaultValue = "")
059    private String defaultValue;
060
061    @XmlAttribute
062    @Metadata(defaultValue = "true")
063    private Boolean required;
064
065    @XmlAttribute
066    @Metadata(defaultValue = "csv")
067    private CollectionFormat collectionFormat;
068
069    @XmlAttribute
070    @Metadata(defaultValue = "string")
071    private String arrayType;
072
073    @XmlAttribute
074    @Metadata(defaultValue = "string")
075    private String dataType;
076
077    @XmlAttribute
078    private String dataFormat;
079
080    @XmlElementWrapper(name = "allowableValues")
081    @XmlElement(name = "value")
082    private List<String> allowableValues;
083
084    @XmlAttribute
085    @Metadata(defaultValue = "")
086    private String access;
087
088    @XmlElement(name = "examples")
089    private List<RestPropertyDefinition> examples;
090
091    public RestOperationParamDefinition() {
092    }
093
094    public RestOperationParamDefinition(VerbDefinition verb) {
095        this.verb = verb;
096    }
097
098    public RestParamType getType() {
099        return type != null ? type : RestParamType.path;
100    }
101
102    /**
103     * Sets the Swagger Parameter type.
104     */
105    public void setType(RestParamType type) {
106        this.type = type;
107    }
108
109    public String getName() {
110        return name;
111    }
112
113    /**
114     * Sets the Swagger Parameter name.
115     */
116    public void setName(String name) {
117        this.name = name;
118    }
119
120    public String getDescription() {
121        return description != null ? description : "";
122    }
123
124    /**
125     * Sets the Swagger Parameter description.
126     */
127    public void setDescription(String description) {
128        this.description = description;
129    }
130
131    /**
132     * Sets the Swagger Parameter default value.
133     */
134    public String getDefaultValue() {
135        return defaultValue != null ? defaultValue : "";
136    }
137
138    public void setDefaultValue(String defaultValue) {
139        this.defaultValue = defaultValue;
140    }
141
142    public Boolean getRequired() {
143        return required != null ? required : true;
144    }
145
146    /**
147     * Sets the Swagger Parameter required flag.
148     */
149    public void setRequired(Boolean required) {
150        this.required = required;
151    }
152
153    public CollectionFormat getCollectionFormat() {
154        return collectionFormat;
155    }
156
157    /**
158     * Sets the Swagger Parameter collection format.
159     */
160    public void setCollectionFormat(CollectionFormat collectionFormat) {
161        this.collectionFormat = collectionFormat;
162    }
163
164    public String getArrayType() {
165        return arrayType;
166    }
167
168    /**
169     * Sets the Swagger Parameter array type.
170     * Required if data type is "array". Describes the type of items in the array.
171     */
172    public void setArrayType(String arrayType) {
173        this.arrayType = arrayType;
174    }
175
176    public String getDataType() {
177        return dataType != null ? dataType : "string";
178    }
179
180    /**
181     * Sets the Swagger Parameter data type.
182     */
183    public void setDataType(String dataType) {
184        this.dataType = dataType;
185    }
186
187    public String getDataFormat() {
188        return dataFormat;
189    }
190
191    /**
192     * Sets the Swagger Parameter data format.
193     */
194    public void setDataFormat(String dataFormat) {
195        this.dataFormat = dataFormat;
196    }
197
198    public List<String> getAllowableValues() {
199        if (allowableValues != null) {
200            return allowableValues;
201        }
202
203        return new ArrayList<String>();
204    }
205
206    /**
207     * Sets the Swagger Parameter list of allowable values (enum).
208     */
209    public void setAllowableValues(List<String> allowableValues) {
210        this.allowableValues = allowableValues;
211    }
212
213    /**
214     * Gets the Swagger Parameter paramAccess flag.
215     *
216     * @deprecated is not in use in swagger specification 2.0
217     */
218    @Deprecated
219    public String getAccess() {
220        return access != null ? access : "";
221    }
222
223    /**
224     * Sets the Swagger Parameter paramAccess flag.
225     *
226     * @deprecated is not in use in swagger specification 2.0
227     */
228    @Deprecated
229    public void setAccess(String access) {
230        this.access = access;
231    }
232
233    public List<RestPropertyDefinition> getExamples() {
234        return examples;
235    }
236
237    /**
238     * Sets the Swagger Parameter examples.
239     */
240    public void setExamples(List<RestPropertyDefinition> examples) {
241        this.examples = examples;
242    }
243
244    /**
245     * Name of the parameter.
246     * <p/>
247     * This option is mandatory.
248     */
249    public RestOperationParamDefinition name(String name) {
250        setName(name);
251        return this;
252    }
253
254    /**
255     * Description of the parameter.
256     */
257    public RestOperationParamDefinition description(String name) {
258        setDescription(name);
259        return this;
260    }
261
262    /**
263     * The default value of the parameter.
264     */
265    public RestOperationParamDefinition defaultValue(String name) {
266        setDefaultValue(name);
267        return this;
268    }
269
270    /**
271     * Whether the parameter is required
272     */
273    public RestOperationParamDefinition required(Boolean required) {
274        setRequired(required);
275        return this;
276    }
277
278    /**
279     * Sets the collection format.
280     */
281    public RestOperationParamDefinition collectionFormat(CollectionFormat collectionFormat) {
282        setCollectionFormat(collectionFormat);
283        return this;
284    }
285
286    /**
287     * The data type of the array data type
288     */
289    public RestOperationParamDefinition arrayType(String arrayType) {
290        setArrayType(arrayType);
291        return this;
292    }
293
294    /**
295     * The data type of the parameter such as <tt>string</tt>, <tt>integer</tt>, <tt>boolean</tt>
296     */
297    public RestOperationParamDefinition dataType(String type) {
298        setDataType(type);
299        return this;
300    }
301
302    /**
303     * The data format of the parameter such as <tt>binary</tt>, <tt>date</tt>, <tt>date-time</tt>, <tt>password</tt>.
304     * The format is usually derived from the dataType alone. However you can set this option for more fine grained control
305     * of the format in use.
306     */
307    public RestOperationParamDefinition dataFormat(String type) {
308        setDataFormat(type);
309        return this;
310    }
311
312    /**
313     * Allowed values of the parameter when its an enum type
314     */
315    public RestOperationParamDefinition allowableValues(List<String> allowableValues) {
316        setAllowableValues(allowableValues);
317        return this;
318    }
319
320    /**
321     * Allowed values of the parameter when its an enum type
322     */
323    public RestOperationParamDefinition allowableValues(String... allowableValues) {
324        setAllowableValues(Arrays.asList(allowableValues));
325        return this;
326    }
327
328    /**
329     * The parameter type such as body, form, header, path, query
330     */
331    public RestOperationParamDefinition type(RestParamType type) {
332        setType(type);
333        return this;
334    }
335
336    /**
337     * Parameter access. Use <tt>false</tt> or <tt>internal</tt> to indicate the parameter
338     * should be hidden for the public.
339     *
340     * @deprecated is not in use in swagger specification 2.0
341     */
342    @Deprecated
343    public RestOperationParamDefinition access(String paramAccess) {
344        setAccess(paramAccess);
345        return this;
346    }
347
348    /**
349     * Adds a body example with the given content-type
350     */
351    public RestOperationParamDefinition example(String contentType, String example) {
352        if (examples == null) {
353            examples = new ArrayList<>();
354        }
355        examples.add(new RestPropertyDefinition(contentType, example));
356        return this;
357    }
358
359    /**
360     * Adds a single example
361     */
362    public RestOperationParamDefinition example(String example) {
363        if (examples == null) {
364            examples = new ArrayList<>();
365        }
366        examples.add(new RestPropertyDefinition("", example));
367        return this;
368    }
369
370    /**
371     * Ends the configuration of this parameter
372     */
373    public RestDefinition endParam() {
374        // name is mandatory
375        StringHelper.notEmpty(name, "name");
376        verb.getParams().add(this);
377        return verb.getRest();
378    }
379
380}