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 java.net.*; 016 017import org.apache.juneau.*; 018 019/** 020 * Various useful static methods for creating Swagger elements. 021 * 022 * <ul class='seealso'> 023 * <li class='link'>{@doc juneau-dto.Swagger} 024 * </ul> 025 */ 026public class SwaggerBuilder { 027 028 /** 029 * Creates an empty {@link Contact} element. 030 * 031 * @return The new element. 032 */ 033 public static final Contact contact() { 034 return new Contact(); 035 } 036 037 /** 038 * Creates an {@link Contact} element with the specified {@link Contact#setName(String) name} attribute. 039 * 040 * @param name The {@link Contact#setName(String) name} attribute. 041 * @return The new element. 042 */ 043 public static final Contact contact(String name) { 044 return contact().name(name); 045 } 046 047 /** 048 * Creates an {@link Contact} element with the specified {@link Contact#setName(String) name}, {@link Contact#setUrl(URI) url}, 049 * and {@link Contact#setEmail(String) email} attributes. 050 * 051 * @param name The {@link Contact#setName(String) name} attribute. 052 * @param url 053 * The {@link Contact#setUrl(URI) url} attribute. 054 * <br>The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 055 * <br>Strings must be valid URIs. 056 * <br>URIs defined by {@link UriResolver} can be used for values. 057 * @param email The {@link Contact#setEmail(String) email} attribute. 058 * @return The new element. 059 */ 060 public static final Contact contact(String name, Object url, String email) { 061 return contact().name(name).url(url).email(email); 062 } 063 064 /** 065 * Creates an empty {@link ExternalDocumentation} element. 066 * 067 * @return The new element. 068 */ 069 public static final ExternalDocumentation externalDocumentation() { 070 return new ExternalDocumentation(); 071 } 072 073 /** 074 * Creates an {@link ExternalDocumentation} element with the specified {@link ExternalDocumentation#setUrl(URI) url} 075 * attribute. 076 * 077 * @param url 078 * The {@link ExternalDocumentation#setUrl(URI) url} attribute. 079 * <br>The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 080 * <br>Strings must be valid URIs. 081 * <br>URIs defined by {@link UriResolver} can be used for values. 082 * @return The new element. 083 */ 084 public static final ExternalDocumentation externalDocumentation(Object url) { 085 return externalDocumentation().url(url); 086 } 087 088 /** 089 * Creates an {@link ExternalDocumentation} element with the specified {@link ExternalDocumentation#setUrl(URI) url} 090 * and {@link ExternalDocumentation#setDescription(String) description} attributes. 091 * 092 * @param url 093 * The {@link ExternalDocumentation#setUrl(URI) url} attribute. 094 * <br>The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 095 * <br>Strings must be valid URIs. 096 * <br>URIs defined by {@link UriResolver} can be used for values. 097 * @param description The {@link ExternalDocumentation#setDescription(String) description} attribute. 098 * @return The new element. 099 */ 100 public static final ExternalDocumentation externalDocumentation(Object url, String description) { 101 return externalDocumentation().url(url).description(description); 102 } 103 104 /** 105 * Creates an empty {@link HeaderInfo} element. 106 * 107 * @return The new element. 108 */ 109 public static final HeaderInfo headerInfo() { 110 return new HeaderInfo(); 111 } 112 113 /** 114 * Creates an {@link HeaderInfo} element with the specified {@link HeaderInfo#setType(String) type} attribute. 115 * 116 * @param type The {@link HeaderInfo#setType(String) type} attribute. 117 * @return The new element. 118 */ 119 public static final HeaderInfo headerInfo(String type) { 120 return headerInfo().type(type); 121 } 122 123 /** 124 * Creates an {@link HeaderInfo} element with the specified {@link HeaderInfo#setType(String) type} attribute. 125 * 126 * <p> 127 * Throws a runtime exception if the type is not valid. 128 * 129 * @param type 130 * The {@link HeaderInfo#setType(String) type} attribute. 131 * <br>Valid values: 132 * <ul> 133 * <li><js>"string"</js> 134 * <li><js>"number"</js> 135 * <li><js>"integer"</js> 136 * <li><js>"boolean"</js> 137 * <li><js>"array"</js> 138 * </ul> 139 * @return The new element. 140 */ 141 public static final HeaderInfo headerInfoStrict(String type) { 142 return headerInfo().strict().type(type); 143 } 144 145 /** 146 * Creates an empty {@link Info} element. 147 * 148 * @return The new element. 149 */ 150 public static final Info info() { 151 return new Info(); 152 } 153 154 /** 155 * Creates an {@link Info} element with the specified {@link Info#setTitle(String) title} and {@link Info#setVersion(String) version} 156 * attributes. 157 * 158 * @param title The {@link Info#setTitle(String) title} attribute. 159 * @param version The {@link Info#setVersion(String) version} attribute. 160 * @return The new element. 161 */ 162 public static final Info info(String title, String version) { 163 return info().title(title).version(version); 164 } 165 166 /** 167 * Creates an empty {@link Items} element. 168 * 169 * @return The new element. 170 */ 171 public static final Items items() { 172 return new Items(); 173 } 174 175 /** 176 * Creates an {@link Items} element with the specified {@link Items#setType(String) type} attribute. 177 * 178 * @param type The {@link Items#setType(String) type} attribute. 179 * @return The new element. 180 */ 181 public static final Items items(String type) { 182 return items().type(type); 183 } 184 185 /** 186 * Creates an {@link Items} element with the specified {@link Items#setType(String) type} attribute. 187 * 188 * <p> 189 * Throws a runtime exception if the type is not valid. 190 * 191 * @param type 192 * The {@link Items#setType(String) type} attribute. 193 * <br>Valid values: 194 * <ul> 195 * <li><js>"string"</js> 196 * <li><js>"number"</js> 197 * <li><js>"integer"</js> 198 * <li><js>"boolean"</js> 199 * <li><js>"array"</js> 200 * </ul> 201 * @return The new element. 202 */ 203 public static final Items itemsStrict(String type) { 204 return items().strict().type(type); 205 } 206 207 /** 208 * Creates an empty {@link License} element. 209 * 210 * @return The new element. 211 */ 212 public static final License license() { 213 return new License(); 214 } 215 216 /** 217 * Creates an {@link License} element with the specified {@link License#setName(String) name} attribute. 218 * 219 * @param name The {@link License#setName(String) name} attribute. 220 * @return The new element. 221 */ 222 public static final License license(String name) { 223 return license().name(name); 224 } 225 226 /** 227 * Creates an {@link License} element with the specified {@link License#setName(String) name} and {@link License#setUrl(URI) url} attributes. 228 * 229 * @param name The {@link License#setName(String) name} attribute. 230 * @param url The {@link License#setUrl(URI) url} attribute. 231 * @return The new element. 232 */ 233 public static final License license(String name, URI url) { 234 return license().name(name).url(url); 235 } 236 237 /** 238 * Creates an empty {@link Operation} element. 239 * 240 * @return The new element. 241 */ 242 public static final Operation operation() { 243 return new Operation(); 244 } 245 246 /** 247 * Creates an empty {@link ParameterInfo} element. 248 * 249 * @return The new element. 250 */ 251 public static final ParameterInfo parameterInfo() { 252 return new ParameterInfo(); 253 } 254 255 /** 256 * Creates an {@link ParameterInfo} element with the specified {@link ParameterInfo#setIn(String) in} and 257 * {@link ParameterInfo#setName(String) name} attributes. 258 * 259 * @param in The {@link ParameterInfo#setIn(String) in} attribute. 260 * @param name The {@link ParameterInfo#setName(String) name} attribute. 261 * @return The new element. 262 */ 263 public static final ParameterInfo parameterInfo(String in, String name) { 264 return parameterInfo().in(in).name(name); 265 } 266 267 /** 268 * Creates an {@link ParameterInfo} element with the specified {@link ParameterInfo#setIn(String) in} and 269 * {@link ParameterInfo#setName(String) name} attributes. 270 * 271 * <p> 272 * Throws a runtime exception if the type is not valid. 273 * 274 * @param in 275 * The {@link ParameterInfo#setIn(String) in} attribute. 276 * <br>Valid values: 277 * <ul> 278 * <li><js>"query"</js> 279 * <li><js>"header"</js> 280 * <li><js>"path"</js> 281 * <li><js>"formData"</js> 282 * <li><js>"body"</js> 283 * </ul> 284 * @param name The {@link ParameterInfo#setName(String) name} attribute. 285 * @return The new element. 286 */ 287 public static final ParameterInfo parameterInfoStrict(String in, String name) { 288 return parameterInfo().strict().in(in).name(name); 289 } 290 291 /** 292 * Creates an empty {@link ResponseInfo} element. 293 * 294 * @return The new element. 295 */ 296 public static final ResponseInfo responseInfo() { 297 return new ResponseInfo(); 298 } 299 300 /** 301 * Creates an {@link ResponseInfo} element with the specified {@link ResponseInfo#setDescription(String) description} attribute. 302 * 303 * @param description The {@link ResponseInfo#setDescription(String) description} attribute. 304 * @return The new element. 305 */ 306 public static final ResponseInfo responseInfo(String description) { 307 return responseInfo().description(description); 308 } 309 310 /** 311 * Creates an empty {@link SchemaInfo} element. 312 * 313 * @return The new element. 314 */ 315 public static final SchemaInfo schemaInfo() { 316 return new SchemaInfo(); 317 } 318 319 /** 320 * Creates an empty {@link SecurityScheme} element. 321 * 322 * @return The new element. 323 */ 324 public static final SecurityScheme securityScheme() { 325 return new SecurityScheme(); 326 } 327 328 /** 329 * Creates an {@link SecurityScheme} element with the specified {@link SecurityScheme#setType(String) type} attribute. 330 * 331 * @param type The {@link SecurityScheme#setType(String) type} attribute. 332 * @return The new element. 333 */ 334 public static final SecurityScheme securityScheme(String type) { 335 return securityScheme().type(type); 336 } 337 338 /** 339 * Creates an {@link SecurityScheme} element with the specified {@link SecurityScheme#setType(String) type} attribute. 340 * 341 * <p> 342 * Throws a runtime exception if the type is not valid. 343 * 344 * @param type 345 * The {@link SecurityScheme#setType(String) type} attribute. 346 * <br>Valid values: 347 * <ul> 348 * <li><js>"basic"</js> 349 * <li><js>"apiKey"</js> 350 * <li><js>"oauth2"</js> 351 * </ul> 352 * @return The new element. 353 */ 354 public static final SecurityScheme securitySchemeStrict(String type) { 355 return securityScheme().strict().type(type); 356 } 357 358 /** 359 * Creates an empty {@link Swagger} element. 360 * 361 * @return The new element. 362 */ 363 public static final Swagger swagger() { 364 return new Swagger(); 365 } 366 367 /** 368 * Creates an {@link Swagger} element with the specified {@link Swagger#setInfo(Info) info} attribute. 369 * 370 * @param info The {@link Swagger#setInfo(Info) info} attribute. 371 * @return The new element. 372 */ 373 public static final Swagger swagger(Info info) { 374 return swagger().info(info); 375 } 376 377 /** 378 * Creates an empty {@link Tag} element. 379 * 380 * @return The new element. 381 */ 382 public static final Tag tag() { 383 return new Tag(); 384 } 385 386 /** 387 * Creates an {@link Tag} element with the specified {@link Tag#setName(String) name} attribute. 388 * 389 * @param name The {@link Tag#setName(String) name} attribute. 390 * @return The new element. 391 */ 392 public static final Tag tag(String name) { 393 return tag().name(name); 394 } 395 396 /** 397 * Creates an empty {@link Xml} element. 398 * 399 * @return The new element. 400 */ 401 public static final Xml xml() { 402 return new Xml(); 403 } 404}