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    @XmlElement(name = "examples")
086    private List<RestPropertyDefinition> examples;
087
088    public RestOperationParamDefinition() {
089    }
090
091    public RestOperationParamDefinition(VerbDefinition verb) {
092        this.verb = verb;
093    }
094
095    public RestParamType getType() {
096        return type != null ? type : RestParamType.path;
097    }
098
099    /**
100     * Sets the Swagger Parameter type.
101     */
102    public void setType(RestParamType type) {
103        this.type = type;
104    }
105
106    public String getName() {
107        return name;
108    }
109
110    /**
111     * Sets the Swagger Parameter name.
112     */
113    public void setName(String name) {
114        this.name = name;
115    }
116
117    public String getDescription() {
118        return description != null ? description : "";
119    }
120
121    /**
122     * Sets the Swagger Parameter description.
123     */
124    public void setDescription(String description) {
125        this.description = description;
126    }
127
128    /**
129     * Sets the Swagger Parameter default value.
130     */
131    public String getDefaultValue() {
132        return defaultValue != null ? defaultValue : "";
133    }
134
135    public void setDefaultValue(String defaultValue) {
136        this.defaultValue = defaultValue;
137    }
138
139    public Boolean getRequired() {
140        return required != null ? required : true;
141    }
142
143    /**
144     * Sets the Swagger Parameter required flag.
145     */
146    public void setRequired(Boolean required) {
147        this.required = required;
148    }
149
150    public CollectionFormat getCollectionFormat() {
151        return collectionFormat;
152    }
153
154    /**
155     * Sets the Swagger Parameter collection format.
156     */
157    public void setCollectionFormat(CollectionFormat collectionFormat) {
158        this.collectionFormat = collectionFormat;
159    }
160
161    public String getArrayType() {
162        return arrayType;
163    }
164
165    /**
166     * Sets the Swagger Parameter array type. Required if data type is "array".
167     * Describes the type of items in the array.
168     */
169    public void setArrayType(String arrayType) {
170        this.arrayType = arrayType;
171    }
172
173    public String getDataType() {
174        return dataType != null ? dataType : "string";
175    }
176
177    /**
178     * Sets the Swagger Parameter data type.
179     */
180    public void setDataType(String dataType) {
181        this.dataType = dataType;
182    }
183
184    public String getDataFormat() {
185        return dataFormat;
186    }
187
188    /**
189     * Sets the Swagger Parameter data format.
190     */
191    public void setDataFormat(String dataFormat) {
192        this.dataFormat = dataFormat;
193    }
194
195    public List<String> getAllowableValues() {
196        if (allowableValues != null) {
197            return allowableValues;
198        }
199
200        return new ArrayList<>();
201    }
202
203    /**
204     * Sets the Swagger Parameter list of allowable values (enum).
205     */
206    public void setAllowableValues(List<String> allowableValues) {
207        this.allowableValues = allowableValues;
208    }
209
210    public List<RestPropertyDefinition> getExamples() {
211        return examples;
212    }
213
214    /**
215     * Sets the Swagger Parameter examples.
216     */
217    public void setExamples(List<RestPropertyDefinition> examples) {
218        this.examples = examples;
219    }
220
221    /**
222     * Name of the parameter.
223     * <p/>
224     * This option is mandatory.
225     */
226    public RestOperationParamDefinition name(String name) {
227        setName(name);
228        return this;
229    }
230
231    /**
232     * Description of the parameter.
233     */
234    public RestOperationParamDefinition description(String name) {
235        setDescription(name);
236        return this;
237    }
238
239    /**
240     * The default value of the parameter.
241     */
242    public RestOperationParamDefinition defaultValue(String name) {
243        setDefaultValue(name);
244        return this;
245    }
246
247    /**
248     * Whether the parameter is required
249     */
250    public RestOperationParamDefinition required(Boolean required) {
251        setRequired(required);
252        return this;
253    }
254
255    /**
256     * Sets the collection format.
257     */
258    public RestOperationParamDefinition collectionFormat(CollectionFormat collectionFormat) {
259        setCollectionFormat(collectionFormat);
260        return this;
261    }
262
263    /**
264     * The data type of the array data type
265     */
266    public RestOperationParamDefinition arrayType(String arrayType) {
267        setArrayType(arrayType);
268        return this;
269    }
270
271    /**
272     * The data type of the parameter such as <tt>string</tt>, <tt>integer</tt>,
273     * <tt>boolean</tt>
274     */
275    public RestOperationParamDefinition dataType(String type) {
276        setDataType(type);
277        return this;
278    }
279
280    /**
281     * The data format of the parameter such as <tt>binary</tt>, <tt>date</tt>,
282     * <tt>date-time</tt>, <tt>password</tt>. The format is usually derived from
283     * the dataType alone. However you can set this option for more fine grained
284     * control of the format in use.
285     */
286    public RestOperationParamDefinition dataFormat(String type) {
287        setDataFormat(type);
288        return this;
289    }
290
291    /**
292     * Allowed values of the parameter when its an enum type
293     */
294    public RestOperationParamDefinition allowableValues(List<String> allowableValues) {
295        setAllowableValues(allowableValues);
296        return this;
297    }
298
299    /**
300     * Allowed values of the parameter when its an enum type
301     */
302    public RestOperationParamDefinition allowableValues(String... allowableValues) {
303        setAllowableValues(Arrays.asList(allowableValues));
304        return this;
305    }
306
307    /**
308     * Allowed values of the parameter when its an enum type
309     */
310    public RestOperationParamDefinition allowableValues(String allowableValues) {
311        setAllowableValues(Arrays.asList(allowableValues.split(",")));
312        return this;
313    }
314
315    /**
316     * The parameter type such as body, form, header, path, query
317     */
318    public RestOperationParamDefinition type(RestParamType type) {
319        setType(type);
320        return this;
321    }
322
323    /**
324     * Adds a body example with the given content-type
325     */
326    public RestOperationParamDefinition example(String contentType, String example) {
327        if (examples == null) {
328            examples = new ArrayList<>();
329        }
330        examples.add(new RestPropertyDefinition(contentType, example));
331        return this;
332    }
333
334    /**
335     * Adds a single example
336     */
337    public RestOperationParamDefinition example(String example) {
338        if (examples == null) {
339            examples = new ArrayList<>();
340        }
341        examples.add(new RestPropertyDefinition("", example));
342        return this;
343    }
344
345    /**
346     * Ends the configuration of this parameter
347     */
348    public RestDefinition endParam() {
349        // name is mandatory
350        StringHelper.notEmpty(name, "name");
351        verb.getParams().add(this);
352        return verb.getRest();
353    }
354
355}