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}