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 java.util.*; 017 018import org.apache.juneau.annotation.*; 019import org.apache.juneau.http.*; 020 021/** 022 * Describes a single API operation on a path. 023 * 024 * <h5 class='section'>Example:</h5> 025 * <p class='bcode'> 026 * <jc>// Construct using SwaggerBuilder.</jc> 027 * Operation x = <jsm>operation</jsm>() 028 * .tags(<js>"pet"</js>) 029 * .summary(<js>"Updates a pet in the store with form data"</js>) 030 * .description(<js>""</js>) 031 * .operationId(<js>"updatePetWithForm"</js>) 032 * .consumes(<js>"application/x-www-form-urlencoded"</js>) 033 * .produces(<js>"application/json"</js>, <js>"application/xml"</js>) 034 * .parameters( 035 * <jsm>parameter</jsm>() 036 * .name(<js>"petId"</js>) 037 * .in(<js>"path"</js>) 038 * .description(<js>"ID of pet that needs to be updated"</js>) 039 * .required(<jk>true</jk>) 040 * .type(<js>"string"</js>), 041 * <jsm>parameter</jsm>() 042 * .name(<js>"name"</js>) 043 * .in(<js>"formData"</js>) 044 * .description(<js>"Updated name of the pet"</js>) 045 * .required(<jk>false</jk>) 046 * .type(<js>"string"</js>), 047 * <jsm>parameter</jsm>() 048 * .name(<js>"status"</js>) 049 * .in(<js>"formData"</js>) 050 * .description(<js>"Updated status of the pet"</js>) 051 * .required(<jk>false</jk>) 052 * .type(<js>"string"</js>) 053 * ) 054 * .response(200, <jsm>responseInfo</jsm>(<js>"Pet updated."</js>)) 055 * .response(405, <jsm>responseInfo</jsm>(<js>"Invalid input."</js>)) 056 * .security(<js>"petstore_auth"</js>, <js>"write:pets"</js>, <js>"read:pets"</js>); 057 * 058 * <jc>// Serialize using JsonSerializer.</jc> 059 * String json = JsonSerializer.<jsf>DEFAULT</jsf>.toString(x); 060 * 061 * <jc>// Or just use toString() which does the same as above.</jc> 062 * String json = x.toString(); 063 * </p> 064 * <p class='bcode'> 065 * <jc>// Output</jc> 066 * { 067 * <js>"tags"</js>: [ 068 * <js>"pet"</js> 069 * ], 070 * <js>"summary"</js>: <js>"Updates a pet in the store with form data"</js>, 071 * <js>"description"</js>: <js>""</js>, 072 * <js>"operationId"</js>: <js>"updatePetWithForm"</js>, 073 * <js>"consumes"</js>: [ 074 * <js>"application/x-www-form-urlencoded"</js> 075 * ], 076 * <js>"produces"</js>: [ 077 * <js>"application/json"</js>, 078 * <js>"application/xml"</js> 079 * ], 080 * <js>"parameters"</js>: [ 081 * { 082 * <js>"name"</js>: <js>"petId"</js>, 083 * <js>"in"</js>: <js>"path"</js>, 084 * <js>"description"</js>: <js>"ID of pet that needs to be updated"</js>, 085 * <js>"required"</js>: <jk>true</jk>, 086 * <js>"type"</js>: <js>"string"</js> 087 * }, 088 * { 089 * <js>"name"</js>: <js>"name"</js>, 090 * <js>"in"</js>: <js>"formData"</js>, 091 * <js>"description"</js>: <js>"Updated name of the pet"</js>, 092 * <js>"required"</js>: <jk>false</jk>, 093 * <js>"type"</js>: <js>"string"</js> 094 * }, 095 * { 096 * <js>"name"</js>: <js>"status"</js>, 097 * <js>"in"</js>: <js>"formData"</js>, 098 * <js>"description"</js>: <js>"Updated status of the pet"</js>, 099 * <js>"required"</js>: <jk>false</jk>, 100 * <js>"type"</js>: <js>"string"</js> 101 * } 102 * ], 103 * <js>"responses"</js>: { 104 * <js>"200"</js>: { 105 * <js>"description"</js>: <js>"Pet updated."</js> 106 * }, 107 * <js>"405"</js>: { 108 * <js>"description"</js>: <js>"Invalid input"</js> 109 * } 110 * }, 111 * <js>"security"</js>: [ 112 * { 113 * <js>"petstore_auth"</js>: [ 114 * <js>"write:pets"</js>, 115 * <js>"read:pets"</js> 116 * ] 117 * } 118 * ] 119 * } 120 * </p> 121 * 122 * <h5 class='section'>See Also:</h5> 123 * <ul class='doctree'> 124 * <li class='link'><a class='doclink' href='../../../../../overview-summary.html#juneau-dto.Swagger'>Overview > juneau-dto > Swagger</a> 125 * </ul> 126 */ 127@Bean(properties="operationId,summary,description,tags,externalDocs,consumes,produces,parameters,responses,schemes,deprecated,security,*") 128public class Operation extends SwaggerElement { 129 130 private String 131 summary, 132 description, 133 operationId; 134 private Boolean deprecated; 135 private ExternalDocumentation externalDocs; 136 private List<String> 137 tags, 138 schemes; 139 private List<MediaType> 140 consumes, 141 produces; 142 private List<ParameterInfo> parameters; 143 private List<Map<String,List<String>>> security; 144 private Map<String,ResponseInfo> responses; 145 146 /** 147 * Bean property getter: <property>tags</property>. 148 * 149 * <p> 150 * A list of tags for API documentation control. 151 * <br>Tags can be used for logical grouping of operations by resources or any other qualifier. 152 * 153 * @return The property value, or <jk>null</jk> if it is not set. 154 */ 155 public List<String> getTags() { 156 return tags; 157 } 158 159 /** 160 * Bean property setter: <property>tags</property>. 161 * 162 * <p> 163 * A list of tags for API documentation control. 164 * <br>Tags can be used for logical grouping of operations by resources or any other qualifier. 165 * 166 * @param value 167 * The new value for this property. 168 * <br>Can be <jk>null</jk> to unset the property. 169 * @return This object (for method chaining). 170 */ 171 public Operation setTags(Collection<String> value) { 172 tags = newList(value); 173 return this; 174 } 175 176 /** 177 * Adds one or more values to the <property>tags</property> property. 178 * 179 * <p> 180 * A list of tags for API documentation control. 181 * <br>Tags can be used for logical grouping of operations by resources or any other qualifier. 182 * 183 * @param value 184 * The values to add to this property. 185 * <br>Ignored if <jk>null</jk>. 186 * @return This object (for method chaining). 187 */ 188 public Operation addTags(Collection<String> value) { 189 tags = addToList(tags, value); 190 return this; 191 } 192 193 /** 194 * Same as {@link #addTags(Collection)}. 195 * 196 * @param values 197 * The values to add to this property. 198 * <br>Valid types: 199 * <ul> 200 * <li><code>Collection<String></code> 201 * <li><code>String</code> - JSON array representation of <code>Collection<String></code> 202 * <h5 class='figure'>Example:</h5> 203 * <p class='bcode'> 204 * tags(<js>"['foo','bar']"</js>); 205 * </p> 206 * <li><code>String</code> - Individual values 207 * <h5 class='figure'>Example:</h5> 208 * <p class='bcode'> 209 * tags(<js>"foo"</js>, <js>"bar"</js>); 210 * </p> 211 * </ul> 212 * @return This object (for method chaining). 213 */ 214 public Operation tags(Object...values) { 215 tags = addToList(tags, values, String.class); 216 return this; 217 } 218 219 /** 220 * Bean property getter: <property>summary</property>. 221 * 222 * <p> 223 * A short summary of what the operation does. 224 * 225 * @return The property value, or <jk>null</jk> if it is not set. 226 */ 227 public String getSummary() { 228 return summary; 229 } 230 231 /** 232 * Bean property setter: <property>summary</property>. 233 * 234 * <p> 235 * A short summary of what the operation does. 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 Operation setSummary(String value) { 243 summary = value; 244 return this; 245 } 246 247 /** 248 * Same as {@link #setSummary(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 Operation summary(Object value) { 257 return setSummary(toStringVal(value)); 258 } 259 260 /** 261 * Bean property getter: <property>description</property>. 262 * 263 * <p> 264 * A verbose explanation of the operation behavior. 265 * 266 * @return The property value, or <jk>null</jk> if it is not set. 267 */ 268 public String getDescription() { 269 return description; 270 } 271 272 /** 273 * Bean property setter: <property>description</property>. 274 * 275 * <p> 276 * A verbose explanation of the operation behavior. 277 * 278 * @param value 279 * The new value for this property. 280 * <br><a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used for rich text representation. 281 * <br>Can be <jk>null</jk> to unset the property. 282 * @return This object (for method chaining). 283 */ 284 public Operation setDescription(String value) { 285 description = value; 286 return this; 287 } 288 289 /** 290 * Same as {@link #setDescription(String)}. 291 * 292 * @param value 293 * The new value for this property. 294 * <br>Non-String values will be converted to String using <code>toString()</code>. 295 * <br><a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used for rich text representation. 296 * <br>Can be <jk>null</jk> to unset the property. 297 * @return This object (for method chaining). 298 */ 299 public Operation description(Object value) { 300 return setDescription(toStringVal(value)); 301 } 302 303 /** 304 * Bean property getter: <property>externalDocs</property>. 305 * 306 * <p> 307 * Additional external documentation for this operation. 308 * 309 * @return The property value, or <jk>null</jk> if it is not set. 310 */ 311 public ExternalDocumentation getExternalDocs() { 312 return externalDocs; 313 } 314 315 /** 316 * Bean property setter: <property>externalDocs</property>. 317 * 318 * <p> 319 * Additional external documentation for this operation. 320 * 321 * @param value 322 * The values to add to this property. 323 * <br>Can be <jk>null</jk> to unset the property. 324 * @return This object (for method chaining). 325 */ 326 public Operation setExternalDocs(ExternalDocumentation value) { 327 externalDocs = value; 328 return this; 329 } 330 331 /** 332 * Same as {@link #setExternalDocs(ExternalDocumentation)}. 333 * 334 * @param value 335 * The new value for this property. 336 * <br>Valid types: 337 * <ul> 338 * <li>{@link ExternalDocumentation} 339 * <li><code>String</code> - JSON object representation of {@link ExternalDocumentation} 340 * <h5 class='figure'>Example:</h5> 341 * <p class='bcode'> 342 * externalDocs(<js>"{description:'description',url:'url'}"</js>); 343 * </p> 344 * </ul> 345 * <br>Can be <jk>null</jk> to unset the property. 346 * @return This object (for method chaining). 347 */ 348 public Operation externalDocs(Object value) { 349 return setExternalDocs(toType(value, ExternalDocumentation.class)); 350 } 351 352 /** 353 * Bean property getter: <property>operationId</property>. 354 * 355 * <p> 356 * Unique string used to identify the operation. 357 * 358 * @return The property value, or <jk>null</jk> if it is not set. 359 */ 360 public String getOperationId() { 361 return operationId; 362 } 363 364 /** 365 * Bean property setter: <property>operationId</property>. 366 * 367 * <p> 368 * Unique string used to identify the operation. 369 * 370 * @param value 371 * The new value for this property. 372 * <br>The id MUST be unique among all operations described in the API. 373 * <br>Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to 374 * follow common programming naming conventions. 375 * <br>Can be <jk>null</jk> to unset the property. 376 * @return This object (for method chaining). 377 */ 378 public Operation setOperationId(String value) { 379 operationId = value; 380 return this; 381 } 382 383 /** 384 * Same as {@link #setOperationId(String)}. 385 * 386 * @param value 387 * The new value for this property. 388 * <br>The id MUST be unique among all operations described in the API. 389 * <br>Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to 390 * follow common programming naming conventions. 391 * <br>Non-String values will be converted to String using <code>toString()</code>. 392 * <br>Can be <jk>null</jk> to unset the property. 393 * @return This object (for method chaining). 394 */ 395 public Operation operationId(Object value) { 396 return setOperationId(toStringVal(value)); 397 } 398 399 /** 400 * Bean property getter: <property>consumes</property>. 401 * 402 * <p> 403 * A list of MIME types the operation can consume. 404 * 405 * <p> 406 * This overrides the <code>consumes</code> definition at the Swagger Object. 407 * <br>An empty value MAY be used to clear the global definition. 408 * 409 * @return The property value, or <jk>null</jk> if it is not set. 410 */ 411 public List<MediaType> getConsumes() { 412 return consumes; 413 } 414 415 /** 416 * Bean property setter: <property>consumes</property>. 417 * 418 * <p> 419 * A list of MIME types the operation can consume. 420 * 421 * <p> 422 * This overrides the <code>consumes</code> definition at the Swagger Object. 423 * <br>An empty value MAY be used to clear the global definition. 424 * 425 * @param value 426 * The new value for this property. 427 * <br>Values MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">Mime Types</a>. 428 * <br>Can be <jk>null</jk> to unset the property. 429 * @return This object (for method chaining). 430 */ 431 public Operation setConsumes(Collection<MediaType> value) { 432 consumes = newList(value); 433 return this; 434 } 435 436 /** 437 * Adds one or more values to the <property>consumes</property> property. 438 * 439 * <p> 440 * A list of MIME types the operation can consume. 441 * 442 * <p> 443 * This overrides the <code>consumes</code> definition at the Swagger Object. 444 * <br>An empty value MAY be used to clear the global definition. 445 * 446 * @param value 447 * The values to add to this property. 448 * <br>Values MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">Mime Types</a>. 449 * <br>Ignored if <jk>null</jk>. 450 * @return This object (for method chaining). 451 */ 452 public Operation addConsumes(Collection<MediaType> value) { 453 consumes = addToList(consumes, value); 454 return this; 455 } 456 457 /** 458 * Adds one or more values to the <property>consumes</property> property. 459 * 460 * @param values 461 * The values to add to this property. 462 * <br>Valid types: 463 * <ul> 464 * <li>{@link MediaType} 465 * <li><code>Collection<{@link MediaType}|String></code> 466 * <li><code>{@link MediaType}[]</code> 467 * <li><code>String</code> - JSON array representation of <code>Collection<{@link MediaType}></code> 468 * <h5 class='figure'>Example:</h5> 469 * <p class='bcode'> 470 * consumes(<js>"['text/json']"</js>); 471 * </p> 472 * <li><code>String</code> - Individual values 473 * <h5 class='figure'>Example:</h5> 474 * <p class='bcode'> 475 * consumes(<js>"text/json"</js>); 476 * </p> 477 * </ul> 478 * <br>Ignored if <jk>null</jk>. 479 * @return This object (for method chaining). 480 */ 481 public Operation consumes(Object...values) { 482 consumes = addToList(consumes, values, MediaType.class); 483 return this; 484 } 485 486 /** 487 * Bean property getter: <property>produces</property>. 488 * 489 * <p> 490 * A list of MIME types the operation can produce. 491 * 492 * <p> 493 * This overrides the <code>produces</code> definition at the Swagger Object. 494 * <br>An empty value MAY be used to clear the global definition. 495 * 496 * @return The property value, or <jk>null</jk> if it is not set. 497 */ 498 public List<MediaType> getProduces() { 499 return produces; 500 } 501 502 /** 503 * Bean property setter: <property>produces</property>. 504 * 505 * <p> 506 * A list of MIME types the operation can produce. 507 * 508 * <p> 509 * This overrides the <code>produces</code> definition at the Swagger Object. 510 * <br>An empty value MAY be used to clear the global definition. 511 * 512 * @param value 513 * The values to add to this property. 514 * <br>Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">Mime Types</a>. 515 * <br>Can be <jk>null</jk> to unset the property. 516 * @return This object (for method chaining). 517 */ 518 public Operation setProduces(Collection<MediaType> value) { 519 produces = newList(value); 520 return this; 521 } 522 523 /** 524 * Adds one or more values to the <property>produces</property> property. 525 * 526 * <p> 527 * A list of MIME types the operation can produces. 528 * 529 * <p> 530 * This overrides the <code>produces</code> definition at the Swagger Object. 531 * <br>An empty value MAY be used to clear the global definition. 532 * 533 * @param value 534 * The values to add to this property. 535 * <br>Ignored if <jk>null</jk>. 536 * @return This object (for method chaining). 537 */ 538 public Operation addProduces(Collection<MediaType> value) { 539 produces = addToList(produces, value); 540 return this; 541 } 542 543 /** 544 * Same as {@link #addProduces(Collection)}. 545 * 546 * @param values 547 * The values to add to this property. 548 * <br>Valid types: 549 * <ul> 550 * <li>{@link MediaType} 551 * <li><code>Collection<{@link MediaType}|String></code> 552 * <li><code>{@link MediaType}[]</code> 553 * <li><code>String</code> - JSON array representation of <code>Collection<{@link MediaType}></code> 554 * <h5 class='figure'>Example:</h5> 555 * <p class='bcode'> 556 * produces(<js>"['text/json']"</js>); 557 * </p> 558 * <li><code>String</code> - Individual values 559 * <h5 class='figure'>Example:</h5> 560 * <p class='bcode'> 561 * produces(<js>"text/json"</js>); 562 * </p> 563 * </ul> 564 * <br>Ignored if <jk>null</jk>. 565 * @return This object (for method chaining). 566 */ 567 public Operation produces(Object...values) { 568 produces = addToList(produces, values, MediaType.class); 569 return this; 570 } 571 572 /** 573 * Bean property getter: <property>parameters</property>. 574 * 575 * <p> 576 * A list of parameters that are applicable for this operation. 577 * 578 * <h5 class='section'>Notes:</h5> 579 * <ul class='spaced-list'> 580 * <li> 581 * If a parameter is already defined at the <a class="doclink" href="http://swagger.io/specification/#pathItemParameters">Path Item</a>, 582 * the new definition will override it, but can never remove it. 583 * <li> 584 * The list MUST NOT include duplicated parameters. 585 * <li> 586 * A unique parameter is defined by a combination of a <code>name</code> and <code>location</code>. 587 * <li> 588 * The list can use the <a class="doclink" href="http://swagger.io/specification/#referenceObject">Reference Object</a> 589 * to link to parameters that are defined at the <a class="doclink" href="http://swagger.io/specification/#swaggerParameters">Swagger Object's parameters</a>. 590 * <li> 591 * There can be one <js>"body"</js> parameter at most. 592 * </ul> 593 * 594 * @return The property value, or <jk>null</jk> if it is not set. 595 */ 596 public List<ParameterInfo> getParameters() { 597 return parameters; 598 } 599 600 /** 601 * Bean property setter: <property>parameters</property>. 602 * 603 * <p> 604 * A list of parameters that are applicable for this operation. 605 * 606 * <h5 class='section'>Notes:</h5> 607 * <ul class='spaced-list'> 608 * <li> 609 * If a parameter is already defined at the <a class="doclink" href="http://swagger.io/specification/#pathItemParameters">Path Item</a>, 610 * the new definition will override it, but can never remove it. 611 * <li> 612 * The list MUST NOT include duplicated parameters. 613 * <li> 614 * A unique parameter is defined by a combination of a <code>name</code> and <code>location</code>. 615 * <li> 616 * The list can use the <a class="doclink" href="http://swagger.io/specification/#referenceObject">Reference Object</a> 617 * to link to parameters that are defined at the <a class="doclink" href="http://swagger.io/specification/#swaggerParameters">Swagger Object's parameters</a>. 618 * <li> 619 * There can be one <js>"body"</js> parameter at most. 620 * </ul> 621 * 622 * @param value 623 * The new value for this property. 624 * <br>Can be <jk>null</jk> to unset the property. 625 * @return This object (for method chaining). 626 */ 627 public Operation setParameters(Collection<ParameterInfo> value) { 628 parameters = newList(value); 629 return this; 630 } 631 632 /** 633 * Adds one or more values to the <property>parameters</property> property. 634 * 635 * <p> 636 * A list of parameters that are applicable for this operation. 637 * 638 * <h5 class='section'>Notes:</h5> 639 * <ul class='spaced-list'> 640 * <li> 641 * If a parameter is already defined at the <a class="doclink" href="http://swagger.io/specification/#pathItemParameters">Path Item</a>, 642 * the new definition will override it, but can never remove it. 643 * <li> 644 * The list MUST NOT include duplicated parameters. 645 * <li> 646 * A unique parameter is defined by a combination of a <code>name</code> and <code>location</code>. 647 * <li> 648 * The list can use the <a class="doclink" href="http://swagger.io/specification/#referenceObject">Reference Object</a> 649 * to link to parameters that are defined at the <a class="doclink" href="http://swagger.io/specification/#swaggerParameters">Swagger Object's parameters</a>. 650 * <li> 651 * There can be one <js>"body"</js> parameter at most. 652 * </ul> 653 * 654 * @param value 655 * The values to add to this property. 656 * <br>Ignored if <jk>null</jk>. 657 * @return This object (for method chaining). 658 */ 659 public Operation addParameters(Collection<ParameterInfo> value) { 660 parameters = addToList(parameters, value); 661 return this; 662 } 663 664 /** 665 * Same as {@link #addParameters(Collection)}. 666 * 667 * @param values 668 * The values to add to this property. 669 * <br>Valid types: 670 * <ul> 671 * <li>{@link ParameterInfo} 672 * <li><code>Collection<{@link ParameterInfo}|String></code> 673 * <li><code>String</code> - JSON array representation of <code>Collection<{@link ParameterInfo}></code> 674 * <h5 class='figure'>Example:</h5> 675 * <p class='bcode'> 676 * parameters(<js>"[{path:'path',id:'id'}]"</js>); 677 * </p> 678 * <li><code>String</code> - JSON object representation of {@link ParameterInfo} 679 * <h5 class='figure'>Example:</h5> 680 * <p class='bcode'> 681 * parameters(<js>"{path:'path',id:'id'}"</js>); 682 * </p> 683 * </ul> 684 * <br>Ignored if <jk>null</jk>. 685 * @return This object (for method chaining). 686 */ 687 public Operation parameters(Object...values) { 688 parameters = addToList(parameters, values, ParameterInfo.class); 689 return this; 690 } 691 692 /** 693 * Bean property getter: <property>responses</property>. 694 * 695 * <p> 696 * The list of possible responses as they are returned from executing this operation. 697 * 698 * @return The property value, or <jk>null</jk> if it is not set. 699 */ 700 public Map<String,ResponseInfo> getResponses() { 701 return responses; 702 } 703 704 /** 705 * Bean property setter: <property>responses</property>. 706 * 707 * <p> 708 * The list of possible responses as they are returned from executing this operation. 709 * 710 * @param value 711 * The new value for this property. 712 * <br>Property value is required. 713 * @return This object (for method chaining). 714 */ 715 public Operation setResponses(Map<String,ResponseInfo> value) { 716 responses = newMap(value); 717 return this; 718 } 719 720 /** 721 * Adds one or more values to the <property>responses</property> property. 722 * 723 * <p> 724 * The list of possible responses as they are returned from executing this operation. 725 * 726 * @param values 727 * The values to add to this property. 728 * <br>Ignored if <jk>null</jk>. 729 * @return This object (for method chaining). 730 */ 731 public Operation addResponses(Map<String,ResponseInfo> values) { 732 responses = addToMap(responses, values); 733 return this; 734 } 735 736 /** 737 * Adds a single value to the <property>responses</property> property. 738 * 739 * @param statusCode The HTTP status code. 740 * @param response The response description. 741 * @return This object (for method chaining). 742 */ 743 public Operation response(String statusCode, ResponseInfo response) { 744 return addResponses(Collections.singletonMap(statusCode, response)); 745 } 746 747 /** 748 * Same as {@link #addResponses(Map)}. 749 * 750 * @param value 751 * The new value for this property. 752 * <br>Valid types: 753 * <ul> 754 * <li><code>Map<Integer,{@link ResponseInfo}|String></code> 755 * <li><code>String</code> - JSON object representation of <code>Map<Integer,{@link ResponseInfo}></code> 756 * <h5 class='figure'>Example:</h5> 757 * <p class='bcode'> 758 * responses(<js>"{'404':{description:'description',...}}"</js>); 759 * </p> 760 * </ul> 761 * @return This object (for method chaining). 762 */ 763 public Operation responses(Object...value) { 764 responses = addToMap(responses, value, String.class, ResponseInfo.class); 765 return this; 766 } 767 768 /** 769 * Bean property getter: <property>schemes</property>. 770 * 771 * <p> 772 * The transfer protocol for the operation. 773 * <br>The value overrides the Swagger Object <code>schemes</code> definition. 774 * 775 * @return The property value, or <jk>null</jk> if it is not set. 776 */ 777 public List<String> getSchemes() { 778 return schemes; 779 } 780 781 /** 782 * Bean property setter: <property>schemes</property>. 783 * 784 * <p> 785 * The transfer protocol for the operation. 786 * <br>The value overrides the Swagger Object <code>schemes</code> definition. 787 * 788 * @param value 789 * The new value for this property. 790 * <br>Valid values: 791 * <ul> 792 * <li><js>"http"</js> 793 * <li><js>"https"</js> 794 * <li><js>"ws"</js> 795 * <li><js>"wss"</js> 796 * </ul> 797 * <br>Can be <jk>null</jk> to unset the property. 798 * @return This object (for method chaining). 799 */ 800 public Operation setSchemes(Collection<String> value) { 801 schemes = newList(value); 802 return this; 803 } 804 805 /** 806 * Adds one or more values to the <property>schemes</property> property. 807 * 808 * <p> 809 * The transfer protocol for the operation. 810 * <br>The value overrides the Swagger Object <code>schemes</code> definition. 811 * 812 * @param value 813 * The values to add to this property. 814 * <br>Ignored if <jk>null</jk>. 815 * @return This object (for method chaining). 816 */ 817 public Operation addSchemes(Collection<String> value) { 818 schemes = addToList(schemes, value); 819 return this; 820 } 821 822 /** 823 * Same as {@link #addSchemes(Collection)}. 824 * 825 * @param values 826 * The new value for this property. 827 * <br>Valid types: 828 * <ul> 829 * <li><code>Collection<String></code> 830 * <li><code>String</code> - JSON array representation of <code>Collection<String></code> 831 * <h5 class='figure'>Example:</h5> 832 * <p class='bcode'> 833 * schemes(<js>"['scheme1','scheme2']"</js>); 834 * </p> 835 * <li><code>String</code> - Individual values 836 * <h5 class='figure'>Example:</h5> 837 * <p class='bcode'> 838 * schemes(<js>"scheme1</js>, <js>"scheme2"</js>); 839 * </p> 840 * </ul> 841 * @return This object (for method chaining). 842 */ 843 public Operation schemes(Object...values) { 844 schemes = addToList(schemes, values, String.class); 845 return this; 846 } 847 848 /** 849 * Bean property getter: <property>deprecated</property>. 850 * 851 * <p> 852 * Declares this operation to be deprecated. 853 * 854 * @return The property value, or <jk>null</jk> if it is not set. 855 */ 856 public Boolean getDeprecated() { 857 return deprecated; 858 } 859 860 /** 861 * Bean property setter: <property>deprecated</property>. 862 * 863 * <p> 864 * Declares this operation to be deprecated. 865 * 866 * @param value T 867 * The new value for this property. 868 * @return This object (for method chaining). 869 */ 870 public Operation setDeprecated(Boolean value) { 871 deprecated = value; 872 return this; 873 } 874 875 /** 876 * Same as {@link #setDeprecated(Boolean)}. 877 * 878 * @param value 879 * The new value for this property. 880 * <br>Non-boolean values will be converted to boolean using <code>Boolean.<jsm>valueOf</jsm>(value.toString())</code>. 881 * <br>Can be <jk>null</jk> to unset the property. 882 * @return This object (for method chaining). 883 */ 884 public Operation deprecated(Object value) { 885 return setDeprecated(toBoolean(value)); 886 } 887 888 /** 889 * Bean property getter: <property>security</property>. 890 * 891 * <p> 892 * A declaration of which security schemes are applied for this operation. 893 * <br>The list of values describes alternative security schemes that can be used (that is, there is a logical OR 894 * between the security requirements). 895 * 896 * <p> 897 * This definition overrides any declared top-level security. 898 * <br>To remove a top-level <code>security</code> declaration, an empty array can be used. 899 * 900 * @return The property value, or <jk>null</jk> if it is not set. 901 */ 902 public List<Map<String,List<String>>> getSecurity() { 903 return security; 904 } 905 906 /** 907 * Bean property setter: <property>security</property>. 908 * 909 * <p> 910 * A declaration of which security schemes are applied for this operation. 911 * <br>The list of values describes alternative security schemes that can be used (that is, there is a logical OR 912 * between the security requirements). 913 * 914 * <p> 915 * This definition overrides any declared top-level security. 916 * <br>To remove a top-level <code>security</code> declaration, an empty array can be used. 917 * 918 * @param value 919 * The new value for this property. 920 * <br>Can be <jk>null</jk> to unset the property. 921 * @return This object (for method chaining). 922 */ 923 public Operation setSecurity(Collection<Map<String,List<String>>> value) { 924 security = newList(value); 925 return this; 926 } 927 928 /** 929 * Adds one or more values to the <property>security</property> property. 930 * 931 * <p> 932 * A declaration of which security schemes are applied for this operation. 933 * <br>The list of values describes alternative security schemes that can be used (that is, there is a logical OR 934 * between the security requirements). 935 * 936 * <p> 937 * This definition overrides any declared top-level security. 938 * <br>To remove a top-level <code>security</code> declaration, an empty array can be used. 939 * 940 * @param values 941 * The values to add to this property. 942 * <br>Ignored if <jk>null</jk>. 943 * The new value for this property. 944 * @return This object (for method chaining). 945 */ 946 public Operation addSecurity(Collection<Map<String,List<String>>> values) { 947 security = addToList(security, values); 948 return this; 949 } 950 951 /** 952 * Same as {@link #addSecurity(Collection)}. 953 * 954 * @param scheme 955 * The scheme name. 956 * @param alternatives 957 * The list of values describes alternative security schemes that can be used (that is, there is a logical OR 958 * between the security requirements). 959 * @return This object (for method chaining). 960 */ 961 public Operation security(String scheme, String...alternatives) { 962 Map<String,List<String>> m = new LinkedHashMap<>(); 963 m.put(scheme, Arrays.asList(alternatives)); 964 return addSecurity(Collections.singletonList(m)); 965 } 966 967 /** 968 * Same as {@link #addSecurity(Collection)}. 969 * 970 * @param value 971 * The new value for this property. 972 * <br>Valid types: 973 * <ul> 974 * <li><code>Map<String,List<String>></code> 975 * <li><code>String</code> - JSON object representation of a <code>Map<String,List<String>></code> 976 * <h5 class='figure'>Example:</h5> 977 * <p class='bcode'> 978 * securities(<js>"{key:['val1','val2']}"</js>); 979 * </p> 980 * </ul> 981 * @return This object (for method chaining). 982 */ 983 @SuppressWarnings({ "unchecked", "rawtypes" }) 984 public Operation securities(Object...value) { 985 security = addToList((List)security, value, Map.class, String.class, List.class, String.class); 986 return this; 987 } 988 989 @Override /* SwaggerElement */ 990 public <T> T get(String property, Class<T> type) { 991 if (property == null) 992 return null; 993 switch (property) { 994 case "tags": return toType(getTags(), type); 995 case "summary": return toType(getSummary(), type); 996 case "description": return toType(getDescription(), type); 997 case "externalDocs": return toType(getExternalDocs(), type); 998 case "operationId": return toType(getOperationId(), type); 999 case "consumes": return toType(getConsumes(), type); 1000 case "produces": return toType(getProduces(), type); 1001 case "parameters": return toType(getParameters(), type); 1002 case "responses": return toType(getResponses(), type); 1003 case "schemes": return toType(getSchemes(), type); 1004 case "deprecated": return toType(getDeprecated(), type); 1005 case "security": return toType(getSecurity(), type); 1006 default: return super.get(property, type); 1007 } 1008 } 1009 1010 @Override /* SwaggerElement */ 1011 public Operation set(String property, Object value) { 1012 if (property == null) 1013 return this; 1014 switch (property) { 1015 case "tags": return setTags(null).tags(value); 1016 case "summary": return summary(value); 1017 case "description": return description(value); 1018 case "externalDocs": return externalDocs(value); 1019 case "operationId": return operationId(value); 1020 case "consumes": return setConsumes(null).consumes(value); 1021 case "produces": return setProduces(null).produces(value); 1022 case "parameters": return setParameters(null).parameters(value); 1023 case "responses": return setResponses(null).responses(value); 1024 case "schemes": return setSchemes(null).schemes(value); 1025 case "deprecated": return deprecated(value); 1026 case "security": return setSecurity(null).securities(value); 1027 default: 1028 super.set(property, value); 1029 return this; 1030 } 1031 } 1032}