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.rest.annotation;
014
015import static java.lang.annotation.RetentionPolicy.*;
016
017import java.lang.annotation.*;
018
019import org.apache.juneau.annotation.*;
020import org.apache.juneau.http.annotation.*;
021
022/**
023 * Extended annotation for {@link Rest#swagger() @Rest(swagger)}.
024 *
025 * <h5 class='section'>See Also:</h5><ul>
026 *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Swagger">Swagger</a>
027 * </ul>
028 */
029@Retention(RUNTIME)
030public @interface Swagger {
031
032   /**
033    * Defines the swagger field <c>/info/contact</c>.
034    *
035    * <p>
036    * A <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> string with the following fields:
037    * <p class='bschema'>
038    *    {
039    *       name: string,
040    *       url: string,
041    *       email: string
042    *    }
043    * </p>
044    *
045    * <p>
046    * The default value pulls the description from the <c>contact</c> entry in the servlet resource bundle.
047    * (e.g. <js>"contact = {name:'John Smith',email:'john.smith@foo.bar'}"</js> or
048    * <js>"MyServlet.contact = {name:'John Smith',email:'john.smith@foo.bar'}"</js>).
049    *
050    * <h5 class='section'>Example:</h5>
051    * <p class='bjava'>
052    *    <ja>@Rest</ja>(
053    *       swagger=<ja>@Swagger</ja>(
054    *          contact=<js>"{name:'John Smith',email:'john.smith@foo.bar'}"</js>
055    *       )
056    *    )
057    * </p>
058    *
059    * <h5 class='section'>Notes:</h5><ul>
060    *    <li class='note'>
061    *       The format is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> object.
062    *       <br>Multiple lines are concatenated with newlines.
063    *    <li class='note'>
064    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>).
065    * </ul>
066    *
067    * @return The annotation value.
068    */
069   Contact contact() default @Contact;
070
071   /**
072    * Defines the swagger field <c>/info/description</c>.
073    *
074    * <h5 class='section'>Example:</h5>
075    * <p class='bjava'>
076    *    <ja>@Rest</ja>(
077    *       swagger=<ja>@Swagger</ja>(
078    *          description={
079    *             <js>"This is a sample server Petstore server based on the Petstore sample at Swagger.io."</js>,
080    *             <js>"You can find out more about Swagger at &lt;a class='link' href='http://swagger.io'&gt;http://swagger.io&lt;/a&gt;."</js>
081    *          }
082    *       )
083    *    )
084    * </p>
085    *
086    * <h5 class='section'>Notes:</h5><ul>
087    *    <li class='note'>
088    *       The format is plain text.
089    *       <br>Multiple lines are concatenated with newlines.
090    *    <li class='note'>
091    *       The precedence of lookup for this field is:
092    *       <ol>
093    *          <li><c>{resource-class}.description</c> property in resource bundle.
094    *          <li>{@link Swagger#description()} on this class, then any parent classes.
095    *          <li>Value defined in Swagger JSON file.
096    *          <li>{@link Rest#description()} on this class, then any parent classes.
097    *       </ol>
098    *    <li class='note'>
099    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>).
100    * </ul>
101    *
102    * @return The annotation value.
103    */
104   String[] description() default {};
105
106   /**
107    * Defines the swagger field <c>/externalDocs</c>.
108    *
109    * <p>
110    * It is used to populate the Swagger external documentation field and to display on HTML pages.
111    *     *
112    * <p>
113    * The default value pulls the description from the <c>externalDocs</c> entry in the servlet resource bundle.
114    * (e.g. <js>"externalDocs = {url:'http://juneau.apache.org'}"</js> or
115    * <js>"MyServlet.externalDocs = {url:'http://juneau.apache.org'}"</js>).
116    *
117    * <h5 class='section'>Example:</h5>
118    * <p class='bjava'>
119    *    <ja>@Rest</ja>(
120    *       swagger=<ja>@Swagger</ja>(
121    *          externalDocs=<ja>@ExternalDocs</ja>(url=<js>"http://juneau.apache.org"</js>)
122    *       )
123    *    )
124    * </p>
125    *
126    * @return The annotation value.
127    */
128   ExternalDocs externalDocs() default @ExternalDocs;
129
130   /**
131    * Defines the swagger field <c>/info/license</c>.
132    *
133    * <p>
134    * It is used to populate the Swagger license field and to display on HTML pages.
135    *
136    * <p>
137    * A <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> string with the following fields:
138    * <p class='bschema'>
139    *    {
140    *       name: string,
141    *       url: string
142    *    }
143    * </p>
144    *
145    * <p>
146    * The default value pulls the description from the <c>license</c> entry in the servlet resource bundle.
147    * (e.g. <js>"license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js> or
148    * <js>"MyServlet.license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>).
149    *
150    * <h5 class='section'>Example:</h5>
151    * <p class='bjava'>
152    *    <ja>@Rest</ja>(
153    *       swagger=<ja>@Swagger</ja>(
154    *          license=<js>"{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>
155    *       )
156    *    )
157    * </p>
158    *
159    * <h5 class='section'>Notes:</h5><ul>
160    *    <li class='note'>
161    *       The format is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> object.
162    *       <br>Multiple lines are concatenated with newlines.
163    *    <li class='note'>
164    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>).
165    * </ul>
166    *
167    * @return The annotation value.
168    */
169   License license() default @License;
170
171   /**
172    * Defines the swagger field <c>/tags</c>.
173    *
174    *
175    * Optional tagging information for the exposed API.
176    *
177    * <p>
178    * It is used to populate the Swagger tags field and to display on HTML pages.
179    *
180    * <p>
181    * A <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> string with the following fields:
182    * <p class='bschema'>
183    *    [
184    *       {
185    *          name: string,
186    *          description: string,
187    *          externalDocs: {
188    *             description: string,
189    *             url: string
190    *          }
191    *       }
192    *    ]
193    * </p>
194    *
195    * <p>
196    * The default value pulls the description from the <c>tags</c> entry in the servlet resource bundle.
197    * (e.g. <js>"tags = [{name:'Foo',description:'Foobar'}]"</js> or
198    * <js>"MyServlet.tags = [{name:'Foo',description:'Foobar'}]"</js>).
199    *
200    * <h5 class='section'>Example:</h5>
201    * <p class='bjava'>
202    *    <ja>@Rest</ja>(
203    *       swagger=<ja>@Swagger</ja>(
204    *          tags=<js>"[{name:'Foo',description:'Foobar'}]"</js>
205    *       )
206    *    )
207    * </p>
208    *
209    * <h5 class='section'>Notes:</h5><ul>
210    *    <li class='note'>
211    *       The format is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> array.
212    *       <br>Multiple lines are concatenated with newlines.
213    *    <li class='note'>
214    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>).
215    * </ul>
216    *
217    * @return The annotation value.
218    */
219   Tag[] tags() default {};
220
221   /**
222    * Defines the swagger field <c>/info/termsOfService</c>.
223    *
224    *
225    * Optional servlet terms-of-service for this API.
226    *
227    * <p>
228    * It is used to populate the Swagger terms-of-service field.
229    *
230    * <p>
231    * The default value pulls the description from the <c>termsOfService</c> entry in the servlet resource bundle.
232    * (e.g. <js>"termsOfService = foo"</js> or <js>"MyServlet.termsOfService = foo"</js>).
233    *
234    * <h5 class='section'>Notes:</h5><ul>
235    *    <li class='note'>
236    *       The format is plain text.
237    *       <br>Multiple lines are concatenated with newlines.
238    *    <li class='note'>
239    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>).
240    * </ul>
241    *
242    * @return The annotation value.
243    */
244   String[] termsOfService() default {};
245
246   /**
247    * Defines the swagger field <c>/info/title</c>.
248    *
249    * <h5 class='section'>Example:</h5>
250    * <p class='bjava'>
251    *    <ja>@Rest</ja>(
252    *       swagger=<ja>@Swagger</ja>(
253    *          title=<js>"Petstore application"</js>
254    *       )
255    *    )
256    * </p>
257    *
258    * <h5 class='section'>Notes:</h5><ul>
259    *    <li class='note'>
260    *       The format is plain-text.
261    *       <br>Multiple lines are concatenated with newlines.
262    *    <li class='note'>
263    *       The precedence of lookup for this field is:
264    *       <ol>
265    *          <li><c>{resource-class}.title</c> property in resource bundle.
266    *          <li>{@link Swagger#title()} on this class, then any parent classes.
267    *          <li>Value defined in Swagger JSON file.
268    *          <li>{@link Rest#title()} on this class, then any parent classes.
269    *       </ol>
270    *    <li class='note'>
271    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>).
272    * </ul>
273    *
274    * @return The annotation value.
275    */
276   String[] title() default {};
277
278   /**
279    * Free-form value for the swagger of a resource.
280    *
281    * <p>
282    * This is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> object that makes up the swagger information for this resource.
283    *
284    * <p>
285    * The following are completely equivalent ways of defining the swagger description of a resource:
286    * <p class='bjava'>
287    *    <jc>// Normal</jc>
288    *    <ja>@Rest</ja>(
289    *       swagger=<ja>@Swagger</ja>(
290    *          title=<js>"Petstore application"</js>,
291    *          description={
292    *             <js>"This is a sample server Petstore server based on the Petstore sample at Swagger.io."</js>,
293    *             <js>"You can find out more about Swagger at &lt;a class='link' href='http://swagger.io'&gt;http://swagger.io&lt;/a&gt;."</js>
294    *          },
295    *          contact=<ja>@Contact</ja>(
296    *             name=<js>"John Smith"</js>,
297    *             email=<js>"john@smith.com"</js>
298    *          ),
299    *          license=<ja>@License</ja>(
300    *             name=<js>"Apache 2.0"</js>,
301    *             url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>
302    *          ),
303    *          version=<js>"2.0"</js>,
304    *          termsOfService=<js>"You are on your own."</js>,
305    *          tags={
306    *             <ja>@Tag</ja>(
307    *                name=<js>"Java"</js>,
308    *                description=<js>"Java utility"</js>,
309    *                externalDocs=<ja>@ExternalDocs</ja>(
310    *                   description=<js>"Home page"</js>,
311    *                   url=<js>"http://juneau.apache.org"</js>
312    *                )
313    *             }
314    *          },
315    *          externalDocs=<ja>@ExternalDocs</ja>(
316    *             description=<js>"Home page"</js>,
317    *             url=<js>"http://juneau.apache.org"</js>
318    *          )
319    *       )
320    *    )
321    * </p>
322    * <p class='bjava'>
323    *    <jc>// Free-form</jc>
324    *    <ja>@Rest</ja>(
325    *       swagger=@Swagger({
326    *          <js>"title: 'Petstore application',"</js>,
327    *          <js>"description: 'This is a sample server Petstore server based on the Petstore sample at Swagger.io.\nYou can find out more about Swagger at &lt;a class='link' href='http://swagger.io'&gt;http://swagger.io&lt;/a&gt;.',"</js>,
328    *          <js>"contact:{"</js>,
329    *             <js>"name: 'John Smith',"</js>,
330    *             <js>"email: 'john@smith.com'"</js>,
331    *          <js>"},"</js>,
332    *          <js>"license:{"</js>,
333    *             <js>"name: 'Apache 2.0',"</js>,
334    *             <js>"url: 'http://www.apache.org/licenses/LICENSE-2.0.html'"</js>,
335    *          <js>"},"</js>,
336    *          <js>"version: '2.0',"</js>,
337    *          <js>"termsOfService: 'You are on your own.',"</js>,
338    *          <js>"tags:["</js>,
339    *             <js>"{"</js>,
340    *                <js>"name: 'Java',"</js>,
341    *                <js>"description: 'Java utility',"</js>,
342    *                <js>"externalDocs:{"</js>,
343    *                   <js>"description: 'Home page',"</js>,
344    *                   <js>"url: 'http://juneau.apache.org'"</js>,
345    *                <js>"}"</js>,
346    *             <js>"}"</js>,
347    *          <js>"],"</js>,
348    *          <js>"externalDocs:{"</js>,
349    *             <js>"description: 'Home page',"</js>,
350    *             <js>"url: 'http://juneau.apache.org'"</js>,
351    *          <js>"}"</js>
352    *       })
353    *    )
354    * </p>
355    * <p class='bjava'>
356    *    <jc>// Free-form with variables</jc>
357    *    <ja>@Rest</ja>(
358    *       swagger=@Swagger(<js>"$F{MyResourceSwagger.json}"</js>)
359    *    )
360    * </p>
361    *
362    * <p>
363    *    The reasons why you may want to use this field include:
364    * <ul>
365    *    <li>You want to pull in the entire Swagger JSON definition for this content from an external source such as a properties file.
366    *    <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification.
367    * </ul>
368    *
369    * <h5 class='section'>Notes:</h5><ul>
370    *    <li class='note'>
371    *       The format is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> object.
372    *    <li class='note'>
373    *       The leading/trailing <c>{ }</c> characters are optional.
374    *       <br>The following two example are considered equivalent:
375    *       <p class='bjava'>
376    *    <ja>@Swagger</ja>(<js>"{title:'Petstore application'}"</js>)
377    *       </p>
378    *       <p class='bjava'>
379    *    <ja>@Swagger</ja>(<js>"title:'Petstore application'"</js>)
380    *       </p>
381    *    <li class='note'>
382    *       Multiple lines are concatenated with newlines so that you can format the value to be readable.
383    *    <li class='note'>
384    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>).
385    *    <li class='note'>
386    *       Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.
387    * </ul>
388    *
389    * @return The annotation value.
390    */
391   String[] value() default {};
392
393   /**
394    * Defines the swagger field <c>/info/version</c>.
395    *
396    *
397    *
398    * Provides the version of the application API (not to be confused with the specification version).
399    *
400    * <p>
401    * It is used to populate the Swagger version field and to display on HTML pages.
402    *
403    * <p>
404    * The default value pulls the description from the <c>version</c> entry in the servlet resource bundle.
405    * (e.g. <js>"version = 2.0"</js> or <js>"MyServlet.version = 2.0"</js>).
406    *
407    * <h5 class='section'>Notes:</h5><ul>
408    *    <li class='note'>
409    *       The format is plain text.
410    *    <li class='note'>
411    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>).
412    * </ul>
413    *
414    * @return The annotation value.
415    */
416   String version() default "";
417}