001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.dto.swagger; 014 015import static org.apache.juneau.internal.BeanPropertyUtils.*; 016import static org.apache.juneau.internal.ArrayUtils.*; 017 018import java.util.*; 019 020import org.apache.juneau.*; 021import org.apache.juneau.annotation.*; 022import org.apache.juneau.internal.*; 023import org.apache.juneau.utils.*; 024 025/** 026 * Allows the definition of a security scheme that can be used by the operations. 027 * 028 * <p> 029 * Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's 030 * common flows (implicit, password, application and access code). 031 * 032 * <h5 class='section'>Example:</h5> 033 * <p class='bcode w800'> 034 * <jc>// Basic authentication sample</jc> 035 * { 036 * <js>"type"</js>: <js>"basic"</js> 037 * } 038 * 039 * <jc>// API key sample</jc> 040 * { 041 * <js>"type"</js>: <js>"apiKey"</js>, 042 * <js>"name"</js>: <js>"api_key"</js>, 043 * <js>"in"</js>: <js>"header"</js> 044 * } 045 * 046 * <jc>// Implicit OAuth2 sample</jc> 047 * { 048 * <js>"type"</js>: <js>"oauth2"</js>, 049 * <js>"authorizationUrl"</js>: <js>"http://swagger.io/api/oauth/dialog"</js>, 050 * <js>"flow"</js>: <js>"implicit"</js>, 051 * <js>"scopes"</js>: { 052 * <js>"write:pets"</js>: <js>"modify pets in your account"</js>, 053 * <js>"read:pets"</js>: <js>"read your pets"</js> 054 * } 055 * } 056 * </p> 057 * 058 * <h5 class='section'>See Also:</h5> 059 * <ul class='doctree'> 060 * <li class='link'>{@doc juneau-dto.Swagger} 061 * </ul> 062 */ 063@Bean(properties="type,description,name,in,flow,authorizationUrl,tokenUrl,scopes,*") 064public class SecurityScheme extends SwaggerElement { 065 066 private static final String[] VALID_TYPES = {"basic", "apiKey", "oauth2"}; 067 068 private String 069 type, 070 description, 071 name, 072 in, 073 flow, 074 authorizationUrl, 075 tokenUrl; 076 private Map<String,String> scopes; 077 078 /** 079 * Default constructor. 080 */ 081 public SecurityScheme() {} 082 083 /** 084 * Copy constructor. 085 * 086 * @param copyFrom The object to copy. 087 */ 088 public SecurityScheme(SecurityScheme copyFrom) { 089 super(copyFrom); 090 091 this.type = copyFrom.type; 092 this.description = copyFrom.description; 093 this.name = copyFrom.name; 094 this.in = copyFrom.in; 095 this.flow = copyFrom.flow; 096 this.authorizationUrl = copyFrom.authorizationUrl; 097 this.tokenUrl = copyFrom.tokenUrl; 098 099 this.scopes = copyFrom.scopes == null ? null : new LinkedHashMap<String,String>(); 100 if (copyFrom.scopes != null) 101 this.scopes.putAll(copyFrom.scopes); 102 } 103 104 /** 105 * Make a deep copy of this object. 106 * 107 * @return A deep copy of this object. 108 */ 109 public SecurityScheme copy() { 110 return new SecurityScheme(this); 111 } 112 113 114 @Override /* SwaggerElement */ 115 protected SecurityScheme strict() { 116 super.strict(); 117 return this; 118 } 119 120 /** 121 * Bean property getter: <property>type</property>. 122 * 123 * <p> 124 * The type of the security scheme. 125 * 126 * @return The property value, or <jk>null</jk> if it is not set. 127 */ 128 public String getType() { 129 return type; 130 } 131 132 /** 133 * Bean property setter: <property>type</property>. 134 * 135 * <p> 136 * The type of the security scheme. 137 * 138 * @param value 139 * The new value for this property. 140 * <br>Valid values: 141 * <ul> 142 * <li><js>"basic"</js> 143 * <li><js>"apiKey"</js> 144 * <li><js>"oauth2"</js> 145 * </ul> 146 * <br>Property value is required. 147 * @return This object (for method chaining). 148 */ 149 public SecurityScheme setType(String value) { 150 if (isStrict() && ! contains(value, VALID_TYPES)) 151 throw new FormattedRuntimeException( 152 "Invalid value passed in to setType(String). Value=''{0}'', valid values={1}", 153 value, VALID_TYPES 154 ); 155 type = value; 156 return this; 157 } 158 159 /** 160 * Same as {@link #setType(String)}. 161 * 162 * @param value 163 * The new value for this property. 164 * <br>Non-String values will be converted to String using <code>toString()</code>. 165 * <br>Valid values: 166 * <ul> 167 * <li><js>"basic"</js> 168 * <li><js>"apiKey"</js> 169 * <li><js>"oauth2"</js> 170 * </ul> 171 * <br>Can be <jk>null</jk> to unset the property. 172 * @return This object (for method chaining). 173 */ 174 public SecurityScheme type(Object value) { 175 return setType(toStringVal(value)); 176 } 177 178 /** 179 * Bean property getter: <property>description</property>. 180 * 181 * <p> 182 * A short description for security scheme. 183 * 184 * @return The property value, or <jk>null</jk> if it is not set. 185 */ 186 public String getDescription() { 187 return description; 188 } 189 190 /** 191 * Bean property setter: <property>description</property>. 192 * 193 * <p> 194 * A short description for security scheme. 195 * 196 * @param value 197 * The new value for this property. 198 * <br>Can be <jk>null</jk> to unset the property. 199 * @return This object (for method chaining). 200 */ 201 public SecurityScheme setDescription(String value) { 202 description = value; 203 return this; 204 } 205 206 /** 207 * Same as {@link #setDescription(String)}. 208 * 209 * @param value 210 * The new value for this property. 211 * <br>Non-String values will be converted to String using <code>toString()</code>. 212 * <br>Can be <jk>null</jk> to unset the property. 213 * @return This object (for method chaining). 214 */ 215 public SecurityScheme description(Object value) { 216 return setDescription(toStringVal(value)); 217 } 218 219 /** 220 * Bean property getter: <property>name</property>. 221 * 222 * <p> 223 * The name of the header or query parameter to be used. 224 * 225 * @return The property value, or <jk>null</jk> if it is not set. 226 */ 227 public String getName() { 228 return name; 229 } 230 231 /** 232 * Bean property setter: <property>name</property>. 233 * 234 * <p> 235 * The name of the header or query parameter to be used. 236 * 237 * @param value 238 * The new value for this property. 239 * <br>Can be <jk>null</jk> to unset the property. 240 * @return This object (for method chaining). 241 */ 242 public SecurityScheme setName(String value) { 243 name = value; 244 return this; 245 } 246 247 /** 248 * Same as {@link #setName(String)}. 249 * 250 * @param value 251 * The new value for this property. 252 * <br>Non-String values will be converted to String using <code>toString()</code>. 253 * <br>Can be <jk>null</jk> to unset the property. 254 * @return This object (for method chaining). 255 */ 256 public SecurityScheme name(Object value) { 257 return setName(toStringVal(value)); 258 } 259 260 /** 261 * Bean property getter: <property>in</property>. 262 * 263 * <p> 264 * The location of the API key. 265 * 266 * @return The property value, or <jk>null</jk> if it is not set. 267 */ 268 public String getIn() { 269 return in; 270 } 271 272 /** 273 * Bean property setter: <property>in</property>. 274 * 275 * <p> 276 * The location of the API key. 277 * 278 * @param value 279 * The new value for this property. 280 * <br>Valid values: 281 * <ul> 282 * <li><js>"query"</js> 283 * <li><js>"header"</js> 284 * </ul> 285 * <br>Can be <jk>null</jk> to unset the property. 286 * @return This object (for method chaining). 287 */ 288 public SecurityScheme setIn(String value) { 289 in = value; 290 return this; 291 } 292 293 /** 294 * Same as {@link #setIn(String)}. 295 * 296 * @param value 297 * The new value for this property. 298 * <br>Non-String values will be converted to String using <code>toString()</code>. 299 * <br>Valid values: 300 * <ul> 301 * <li><js>"query"</js> 302 * <li><js>"header"</js> 303 * </ul> 304 * <br>Can be <jk>null</jk> to unset the property. 305 * @return This object (for method chaining). 306 */ 307 public SecurityScheme in(Object value) { 308 return setIn(toStringVal(value)); 309 } 310 311 /** 312 * Bean property getter: <property>flow</property>. 313 * 314 * <p> 315 * The flow used by the OAuth2 security scheme. 316 * 317 * @return The property value, or <jk>null</jk> if it is not set. 318 */ 319 public String getFlow() { 320 return flow; 321 } 322 323 /** 324 * Bean property setter: <property>flow</property>. 325 * 326 * <p> 327 * The flow used by the OAuth2 security scheme. 328 * 329 * @param value 330 * The new value for this property. 331 * <br>Valid values: 332 * <ul> 333 * <li><js>"implicit"</js> 334 * <li><js>"password"</js> 335 * <li><js>"application"</js> 336 * <li><js>"accessCode"</js> 337 * </ul> 338 * <br>Can be <jk>null</jk> to unset the property. 339 * @return This object (for method chaining). 340 */ 341 public SecurityScheme setFlow(String value) { 342 flow = value; 343 return this; 344 } 345 346 /** 347 * Same as {@link #setFlow(String)}. 348 * 349 * @param value 350 * The new value for this property. 351 * <br>Non-String values will be converted to String using <code>toString()</code>. 352 * <br>Valid values: 353 * <ul> 354 * <li><js>"implicit"</js> 355 * <li><js>"password"</js> 356 * <li><js>"application"</js> 357 * <li><js>"accessCode"</js> 358 * </ul> 359 * <br>Can be <jk>null</jk> to unset the property. 360 * @return This object (for method chaining). 361 */ 362 public SecurityScheme flow(Object value) { 363 return setFlow(toStringVal(value)); 364 } 365 366 /** 367 * Bean property getter: <property>authorizationUrl</property>. 368 * 369 * <p> 370 * The authorization URL to be used for this flow. 371 * 372 * @return The property value, or <jk>null</jk> if it is not set. 373 */ 374 public String getAuthorizationUrl() { 375 return authorizationUrl; 376 } 377 378 /** 379 * Bean property setter: <property>authorizationUrl</property>. 380 * 381 * <p> 382 * The authorization URL to be used for this flow. 383 * 384 * @param value 385 * The new value for this property. 386 * <br>This SHOULD be in the form of a URL. 387 * <br>Can be <jk>null</jk> to unset the property. 388 * @return This object (for method chaining). 389 */ 390 public SecurityScheme setAuthorizationUrl(String value) { 391 authorizationUrl = value; 392 return this; 393 } 394 395 /** 396 * Same as {@link #setAuthorizationUrl(String)}. 397 * 398 * @param value 399 * The new value for this property. 400 * <br>Non-String values will be converted to String using <code>toString()</code>. 401 * <br>This SHOULD be in the form of a URL. 402 * <br>Can be <jk>null</jk> to unset the property. 403 * @return This object (for method chaining). 404 */ 405 public SecurityScheme authorizationUrl(Object value) { 406 return setAuthorizationUrl(toStringVal(value)); 407 } 408 409 /** 410 * Bean property getter: <property>tokenUrl</property>. 411 * 412 * <p> 413 * The token URL to be used for this flow. 414 * 415 * @return The property value, or <jk>null</jk> if it is not set. 416 */ 417 public String getTokenUrl() { 418 return tokenUrl; 419 } 420 421 /** 422 * Bean property setter: <property>tokenUrl</property>. 423 * 424 * <p> 425 * The token URL to be used for this flow. 426 * 427 * @param value 428 * The new value for this property. 429 * <br>This SHOULD be in the form of a URL. 430 * <br>Can be <jk>null</jk> to unset the property. 431 * @return This object (for method chaining). 432 */ 433 public SecurityScheme setTokenUrl(String value) { 434 tokenUrl = value; 435 return this; 436 } 437 438 /** 439 * Same as {@link #setTokenUrl(String)}. 440 * 441 * @param value 442 * The new value for this property. 443 * <br>Non-String values will be converted to String using <code>toString()</code>. 444 * <br>This SHOULD be in the form of a URL. 445 * <br>Can be <jk>null</jk> to unset the property. 446 * @return This object (for method chaining). 447 */ 448 public SecurityScheme tokenUrl(Object value) { 449 return setTokenUrl(toStringVal(value)); 450 } 451 452 /** 453 * Bean property getter: <property>scopes</property>. 454 * 455 * <p> 456 * The available scopes for the OAuth2 security scheme. 457 * 458 * @return The property value, or <jk>null</jk> if it is not set. 459 */ 460 public Map<String,String> getScopes() { 461 return scopes; 462 } 463 464 /** 465 * Bean property setter: <property>scopes</property>. 466 * 467 * <p> 468 * The available scopes for the OAuth2 security scheme. 469 * 470 * @param value 471 * The new value for this property. 472 * <br>Can be <jk>null</jk> to unset the property. 473 * @return This object (for method chaining). 474 */ 475 public SecurityScheme setScopes(Map<String,String> value) { 476 scopes = newMap(value); 477 return this; 478 } 479 480 /** 481 * Adds one or more values to the <property>scopes</property> property. 482 * 483 * @param values 484 * The values to add to this property. 485 * <br>Ignored if <jk>null</jk>. 486 * @return This object (for method chaining). 487 */ 488 public SecurityScheme addScopes(Map<String,String> values) { 489 scopes = addToMap(scopes, values); 490 return this; 491 } 492 493 /** 494 * Adds one or more values to the <property>enum</property> property. 495 * 496 * @param values 497 * The values to add to this property. 498 * <br>Valid types: 499 * <ul> 500 * <li><code>Map<String,{@link HeaderInfo}|String></code> 501 * <li><code>String</code> - JSON object representation of <code>Map<String,{@link HeaderInfo}></code> 502 * <h5 class='figure'>Example:</h5> 503 * <p class='bcode w800'> 504 * scopes(<js>"{name:'value'}"</js>); 505 * </p> 506 * </ul> 507 * <br>Ignored if <jk>null</jk>. 508 * @return This object (for method chaining). 509 */ 510 public SecurityScheme scopes(Object...values) { 511 scopes = addToMap(scopes, values, String.class, String.class); 512 return this; 513 } 514 515 @Override /* SwaggerElement */ 516 public <T> T get(String property, Class<T> type) { 517 if (property == null) 518 return null; 519 switch (property) { 520 case "type": return toType(getType(), type); 521 case "description": return toType(getDescription(), type); 522 case "name": return toType(getName(), type); 523 case "in": return toType(getIn(), type); 524 case "flow": return toType(getFlow(), type); 525 case "authorizationUrl": return toType(getAuthorizationUrl(), type); 526 case "tokenUrl": return toType(getTokenUrl(), type); 527 case "scopes": return toType(getScopes(), type); 528 default: return super.get(property, type); 529 } 530 } 531 532 @Override /* SwaggerElement */ 533 public SecurityScheme set(String property, Object value) { 534 if (property == null) 535 return this; 536 switch (property) { 537 case "type": return type(value); 538 case "description": return description(value); 539 case "name": return name(value); 540 case "in": return in(value); 541 case "flow": return flow(value); 542 case "authorizationUrl": return authorizationUrl(value); 543 case "tokenUrl": return tokenUrl(value); 544 case "scopes": return setScopes(null).scopes(value); 545 default: 546 super.set(property, value); 547 return this; 548 } 549 } 550 551 @Override /* SwaggerElement */ 552 public Set<String> keySet() { 553 ASet<String> s = new ASet<String>() 554 .appendIf(type != null, "type") 555 .appendIf(description != null, "description") 556 .appendIf(name != null, "name") 557 .appendIf(in != null, "in") 558 .appendIf(flow != null, "flow") 559 .appendIf(authorizationUrl != null, "authorizationUrl") 560 .appendIf(tokenUrl != null, "tokenUrl") 561 .appendIf(scopes != null, "scopes"); 562 return new MultiSet<>(s, super.keySet()); 563 } 564}