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