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}