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