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}