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