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.ElementType.*;
016import static java.lang.annotation.RetentionPolicy.*;
017
018import java.lang.annotation.*;
019import java.nio.charset.*;
020
021import org.apache.juneau.*;
022import org.apache.juneau.annotation.*;
023import org.apache.juneau.rest.*;
024import org.apache.juneau.rest.converter.*;
025import org.apache.juneau.rest.guard.*;
026import org.apache.juneau.rest.httppart.*;
027import org.apache.juneau.rest.matcher.*;
028import org.apache.juneau.rest.servlet.*;
029import org.apache.juneau.rest.swagger.*;
030import org.apache.juneau.serializer.*;
031import org.apache.juneau.dto.swagger.*;
032import org.apache.juneau.encoders.*;
033
034/**
035 * Identifies a REST OPTIONS operation Java method on a {@link RestServlet} implementation class.
036 *
037 * <p>
038 * This is a specialized subtype of <c><ja>{@link RestOp @RestOp}(method=<jsf>OPTIONS</jsf>)</c>.
039 *
040 * <h5 class='section'>See Also:</h5><ul>
041 *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.RestOpAnnotatedMethods">@RestOp-Annotated Methods</a>
042
043 * </ul>
044 */
045@Target(METHOD)
046@Retention(RUNTIME)
047@Inherited
048@ContextApply(RestGetAnnotation.RestOpContextApply.class)
049@AnnotationGroup(RestOp.class)
050public @interface RestOptions {
051
052   /**
053    * Specifies whether this method can be called based on the client version.
054    *
055    * <p>
056    * The client version is identified via the HTTP request header identified by
057    * {@link Rest#clientVersionHeader() @Rest(clientVersionHeader)} which by default is <js>"Client-Version"</js>.
058    *
059    * <p>
060    * This is a specialized kind of {@link RestMatcher} that allows you to invoke different Java methods for the same
061    * method/path based on the client version.
062    *
063    * <p>
064    * The format of the client version range is similar to that of OSGi versions.
065    *
066    * <p>
067    * In the following example, the Java methods are mapped to the same HTTP method and URL <js>"/foobar"</js>.
068    * <p class='bjava'>
069    *    <jc>// Call this method if Client-Version is at least 2.0.
070    *    // Note that this also matches 2.0.1.</jc>
071    *    <ja>@RestOptions</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>)
072    *    <jk>public</jk> Object method1()  {...}
073    *
074    *    <jc>// Call this method if Client-Version is at least 1.1, but less than 2.0.</jc>
075    *    <ja>@RestOptions</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>)
076    *    <jk>public</jk> Object method2()  {...}
077    *
078    *    <jc>// Call this method if Client-Version is less than 1.1.</jc>
079    *    <ja>@RestOptions</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[0,1.1)"</js>)
080    *    <jk>public</jk> Object method3()  {...}
081    * </p>
082    *
083    * <p>
084    * It's common to combine the client version with transforms that will convert new POJOs into older POJOs for
085    * backwards compatibility.
086    * <p class='bjava'>
087    *    <jc>// Call this method if Client-Version is at least 2.0.</jc>
088    *    <ja>@RestOptions</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>)
089    *    <jk>public</jk> NewPojo newMethod()  {...}
090    *
091    *    <jc>// Call this method if Client-Version is at least 1.1, but less than 2.0.</jc>
092    *    <ja>@RestOptions</ja>(path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>)
093    *    <ja>@BeanConfig(swaps=NewToOldSwap.<jk>class</jk>)
094    *    <jk>public</jk> NewPojo oldMethod() {
095    *       <jk>return</jk> newMethod();
096    *    }
097    * </p>
098    *
099    * <p>
100    * Note that in the previous example, we're returning the exact same POJO, but using a transform to convert it into
101    * an older form.
102    * The old method could also just return back a completely different object.
103    * The range can be any of the following:
104    * <ul>
105    *    <li><js>"[0,1.0)"</js> = Less than 1.0.  1.0 and 1.0.0 does not match.
106    *    <li><js>"[0,1.0]"</js> = Less than or equal to 1.0.  Note that 1.0.1 will match.
107    *    <li><js>"1.0"</js> = At least 1.0.  1.0 and 2.0 will match.
108    * </ul>
109    *
110    * <h5 class='section'>See Also:</h5><ul>
111    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#clientVersionHeader(String)}
112    * </ul>
113    *
114    * @return The annotation value.
115    */
116   String clientVersion() default "";
117
118   /**
119    * Class-level response converters.
120    *
121    * <p>
122    * Associates one or more {@link RestConverter converters} with this method.
123    *
124    * <h5 class='section'>See Also:</h5><ul>
125    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#converters()} - Registering converters with REST resources.
126    * </ul>
127    *
128    * @return The annotation value.
129    */
130   Class<? extends RestConverter>[] converters() default {};
131
132   /**
133    * Enable debug mode.
134    *
135    * <p>
136    * Enables the following:
137    * <ul class='spaced-list'>
138    *    <li>
139    *       HTTP request/response bodies are cached in memory for logging purposes.
140    *    <li>
141    *       Request/response messages are automatically logged.
142    * </ul>
143    *
144    * <ul class='values'>
145    *    <li><js>"true"</js> - Debug is enabled for all requests.
146    *    <li><js>"false"</js> - Debug is disabled for all requests.
147    *    <li><js>"conditional"</js> - Debug is enabled only for requests that have a <c class='snippet'>Debug: true</c> header.
148    *    <li><js>""</js> (or anything else) - Debug mode is inherited from class.
149    * </ul>
150    *
151    * <h5 class='section'>Notes:</h5><ul>
152    *    <li class='note'>
153    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
154    *       (e.g. <js>"$L{my.localized.variable}"</js>).
155    * </ul>
156    *
157    * <h5 class='section'>See Also:</h5><ul>
158    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#debugEnablement()}
159    * </ul>
160    *
161    * @return The annotation value.
162    */
163   String debug() default "";
164
165   /**
166    * Default <c>Accept</c> header.
167    *
168    * <p>
169    * The default value for the <c>Accept</c> header if not specified on a request.
170    *
171    * <p>
172    * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header.
173    *
174    * @return The annotation value.
175    */
176   String defaultAccept() default "";
177
178   /**
179    * Default character encoding.
180    *
181    * <p>
182    * The default character encoding for the request and response if not specified on the request.
183    *
184    * <h5 class='section'>Notes:</h5><ul>
185    *    <li class='note'>
186    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
187    *       (e.g. <js>"$S{mySystemProperty}"</js>).
188    * </ul>
189    *
190    * <h5 class='section'>See Also:</h5><ul>
191    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultCharset(Charset)}
192    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#defaultCharset(Charset)}
193    *    <li class='ja'>{@link Rest#defaultCharset}
194    * </ul>
195    *
196    * @return The annotation value.
197    */
198   String defaultCharset() default "";
199
200   /**
201    * Specifies default values for query parameters.
202    *
203    * <p>
204    * Strings are of the format <js>"name=value"</js>.
205    *
206    * <p>
207    * Affects values returned by {@link RestRequest#getQueryParam(String)} when the parameter is not present on the request.
208    *
209    * <h5 class='section'>Example:</h5>
210    * <p class='bjava'>
211    *    <ja>@RestOptions</ja>(path=<js>"/*"</js>, defaultRequestQueryData={<js>"foo=bar"</js>})
212    *    <jk>public</jk> String doGet(<ja>@Query</ja>(<js>"foo"</js>) String <jv>foo</jv>)  {...}
213    * </p>
214    *
215    * <h5 class='section'>Notes:</h5><ul>
216    *    <li class='note'>
217    *       You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter.
218    *    <li class='note'>
219    *       Key and value is trimmed of whitespace.
220    *    <li class='note'>
221    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
222    *       (e.g. <js>"$S{mySystemProperty}"</js>).
223    * </ul>
224    *
225    * @return The annotation value.
226    */
227   String[] defaultRequestQueryData() default {};
228
229   /**
230    * Default request attributes.
231    *
232    * <p>
233    * Specifies default values for request attributes if they're not already set on the request.
234    *
235    * <p>
236    * Affects values returned by the following methods:
237    *    <ul>
238    *       <li class='jm'>{@link RestRequest#getAttribute(String)}.
239    *       <li class='jm'>{@link RestRequest#getAttributes()}.
240    *    </ul>
241    *
242    * <h5 class='section'>Example:</h5>
243    * <p class='bjava'>
244    *    <jc>// Defined via annotation resolving to a config file setting with default value.</jc>
245    *    <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: $C{REST/myAttributeValue}"</js>})
246    *    <jk>public class</jk> MyResource {
247    *
248    *       <jc>// Override at the method level.</jc>
249    *       <ja>@RestOptions</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>})
250    *       <jk>public</jk> Object myMethod() {...}
251    *    }
252    * </p>
253    *
254    * </ul>
255    * <h5 class='section'>Notes:</h5><ul>
256    *    <li class='note'>
257    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
258    *       (e.g. <js>"$L{my.localized.variable}"</js>).
259    * </ul>
260    *
261    * <h5 class='section'>See Also:</h5><ul>
262    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultRequestAttributes(NamedAttribute...)}
263    *    <li class='ja'>{@link Rest#defaultRequestAttributes()}
264    * </ul>
265    *
266    * @return The annotation value.
267    */
268   String[] defaultRequestAttributes() default {};
269
270   /**
271    * Default request headers.
272    *
273    * <p>
274    * Specifies default values for request headers if they're not passed in through the request.
275    *
276    * <h5 class='section'>Example:</h5>
277    * <p class='bjava'>
278    *    <jc>// Assume "text/json" Accept value when Accept not specified</jc>
279    *    <ja>@RestOptions</ja>(path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>})
280    *    <jk>public</jk> String doGet()  {...}
281    * </p>
282    *
283    * <h5 class='section'>Notes:</h5><ul>
284    *    <li class='note'>
285    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
286    *       (e.g. <js>"$S{mySystemProperty}"</js>).
287    * </ul>
288    *
289    * <h5 class='section'>See Also:</h5><ul>
290    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultRequestHeaders(org.apache.http.Header...)}
291    * </ul>
292    *
293    * @return The annotation value.
294    */
295   String[] defaultRequestHeaders() default {};
296
297   /**
298    * Default response headers.
299    *
300    * <p>
301    * Specifies default values for response headers if they're not overwritten during the request.
302    *
303    * <h5 class='section'>Example:</h5>
304    * <p class='bjava'>
305    *    <jc>// Assume "text/json" Accept value when Accept not specified</jc>
306    *    <ja>@RestOptions</ja>(path=<js>"/*"</js>, defaultResponseHeaders={<js>"Content-Type: text/json"</js>})
307    *    <jk>public</jk> String doGet()  {...}
308    * </p>
309    *
310    * <h5 class='section'>Notes:</h5><ul>
311    *    <li class='note'>
312    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
313    *       (e.g. <js>"$S{mySystemProperty}"</js>).
314    * </ul>
315    *
316    * <h5 class='section'>See Also:</h5><ul>
317    *    <li class='jm'>{@link org.apache.juneau.rest.RestContext.Builder#defaultResponseHeaders(org.apache.http.Header...)}
318    * </ul>
319    *
320    * @return The annotation value.
321    */
322   String[] defaultResponseHeaders() default {};
323
324   /**
325    * Optional description for the exposed API.
326    *
327    * <p>
328    * This description is used in the following locations:
329    * <ul class='spaced-list'>
330    *    <li>
331    *       The value returned by {@link Operation#getDescription()} in the auto-generated swagger.
332    *    <li>
333    *       The <js>"$RS{operationDescription}"</js> variable.
334    *    <li>
335    *       The description of the method in the Swagger page.
336    * </ul>
337    *
338    * <h5 class='section'>Notes:</h5><ul>
339    *    <li class='note'>
340    *       Corresponds to the swagger field <c>/paths/{path}/{method}/description</c>.
341    *    <li class='note'>
342    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
343    *       (e.g. <js>"$L{my.localized.variable}"</js>).
344    * </ul>
345    *
346    * @return The annotation value.
347    */
348   String[] description() default {};
349
350   /**
351    * Specifies the compression encoders for this method.
352    *
353    * <p>
354    * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses.
355    *
356    * <p>
357    * This value overrides encoders specified at the class level using {@link Rest#encoders()}.
358    * The {@link org.apache.juneau.encoders.EncoderSet.Inherit} class can be used to include values from the parent class.
359    *
360    * <h5 class='section'>Example:</h5>
361    * <p class='bjava'>
362    *    <jc>// Define a REST resource that handles GZIP compression.</jc>
363    *    <ja>@Rest</ja>(
364    *       encoders={
365    *          GzipEncoder.<jk>class</jk>
366    *       }
367    *    )
368    *    <jk>public class</jk> MyResource {
369    *
370    *       <jc>// Define a REST method that can also use a custom encoder.</jc>
371    *       <ja>@RestOptions</ja>(
372    *          method=<jsf>GET</jsf>,
373    *          encoders={
374    *             EncoderSet.Inherit.<jk>class</jk>, MyEncoder.<jk>class</jk>
375    *          }
376    *       )
377    *       <jk>public</jk> MyBean doGet() {
378    *          ...
379    *       }
380    *    }
381    * </p>
382    *
383    * <p>
384    * The programmatic equivalent to this annotation is:
385    * <p class='bjava'>
386    *    RestOpContext.Builder <jv>builder</jv> = RestOpContext.<jsm>create</jsm>(<jv>method</jv>,<jv>restContext</jv>);
387    *    <jv>builder</jv>.getEncoders().set(<jv>classes</jv>);
388    * </p>
389    *
390    * <h5 class='section'>See Also:</h5><ul>
391    *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Encoders">Encoders</a>
392    * </ul>
393    *
394    * @return The annotation value.
395    */
396   Class<? extends Encoder>[] encoders() default {};
397
398   /**
399    * Method-level guards.
400    *
401    * <p>
402    * Associates one or more {@link RestGuard RestGuards} with this method.
403    *
404    * <h5 class='section'>See Also:</h5><ul>
405    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#guards()}
406    * </ul>
407    *
408    * @return The annotation value.
409    */
410   Class<? extends RestGuard>[] guards() default {};
411
412   /**
413    * Method matchers.
414    *
415    * <p>
416    * Associates one more more {@link RestMatcher RestMatchers} with this method.
417    *
418    * <p>
419    * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but
420    * differing based on some request attribute, such as a specific header value.
421    *
422    * <h5 class='section'>See Also:</h5><ul>
423    *    <li class='jac'>{@link RestMatcher}
424    * </ul>
425    *
426    * @return The annotation value.
427    */
428   Class<? extends RestMatcher>[] matchers() default {};
429
430   /**
431    * Dynamically apply this annotation to the specified methods.
432    *
433    * <h5 class='section'>See Also:</h5><ul>
434    *    <li class='link'><a class="doclink" href="../../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
435    * </ul>
436    *
437    * @return The annotation value.
438    */
439   String[] on() default {};
440
441   /**
442    * Optional path pattern for the specified method.
443    *
444    * <p>
445    * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too.
446    * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact
447    * pattern is not found.
448    *
449    * <p>
450    * The path can contain variables that get resolved to {@link org.apache.juneau.http.annotation.Path @Path} parameters.
451    *
452    * <h5 class='figure'>Examples:</h5>
453    * <p class='bjava'>
454    *    <ja>@RestOptions</ja>(path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
455    * </p>
456    * <p class='bjava'>
457    *    <ja>@RestOptions</ja>(path=<js>"/myurl/{0}/{1}/{2}/*"</js>)
458    * </p>
459    *
460    * <p>
461    * Note that you can also use {@link #value()} to specify the path.
462    *
463    * <h5 class='section'>See Also:</h5><ul>
464    *    <li class='ja'>{@link org.apache.juneau.http.annotation.Path}
465    * </ul>
466    *
467    * @return The annotation value.
468    */
469   String[] path() default {};
470
471   /**
472    * Supported accept media types.
473    *
474    * <p>
475    * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource.
476    *
477    * <h5 class='section'>Notes:</h5><ul>
478    *    <li class='note'>
479    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
480    *       (e.g. <js>"$S{mySystemProperty}"</js>).
481    * </ul>
482    *
483    * <h5 class='section'>See Also:</h5><ul>
484    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#produces(MediaType...)}
485    * </ul>
486    *
487    * @return The annotation value.
488    */
489   String[] produces() default {};
490
491   /**
492    * Role guard.
493    *
494    * <p>
495    * An expression defining if a user with the specified roles are allowed to access this method.
496    *
497    * <h5 class='section'>Example:</h5>
498    * <p class='bjava'>
499    *    <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {
500    *
501    *       <ja>@RestOptions</ja>(
502    *          path=<js>"/foo"</js>,
503    *          roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE &amp;&amp; ROLE_SPECIAL)"</js>
504    *       )
505    *       <jk>public</jk> Object doGet() {
506    *       }
507    *    }
508    * </p>
509    *
510    * <h5 class='section'>Notes:</h5><ul>
511    *    <li class='note'>
512    *       Supports any of the following expression constructs:
513    *       <ul>
514    *          <li><js>"foo"</js> - Single arguments.
515    *          <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments.
516    *          <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax.
517    *          <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax.
518    *          <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>.
519    *          <li><js>"fo* &amp; *oo"</js> - Multiple AND'ed arguments, ampersand syntax.
520    *          <li><js>"fo* &amp;&amp; *oo"</js> - Multiple AND'ed arguments, Java-AND syntax.
521    *          <li><js>"fo* || (*oo || bar)"</js> - Parenthesis.
522    *       </ul>
523    *    <li class='note'>
524    *       AND operations take precedence over OR operations (as expected).
525    *    <li class='note'>
526    *       Whitespace is ignored.
527    *    <li class='note'>
528    *       <jk>null</jk> or empty expressions always match as <jk>false</jk>.
529    *    <li class='note'>
530    *       If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()} or {@link org.apache.juneau.rest.RestOpContext.Builder#rolesDeclared(String...)}.
531    *    <li class='note'>
532    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
533    *       (e.g. <js>"$L{my.localized.variable}"</js>).
534    *    <li class='note'>
535    *       When defined on parent/child classes and methods, ALL guards within the hierarchy must pass.
536    * </ul>
537    *
538    * <h5 class='section'>See Also:</h5><ul>
539    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#roleGuard(String)}
540    * </ul>
541    *
542    * @return The annotation value.
543    */
544   String roleGuard() default "";
545
546   /**
547    * Declared roles.
548    *
549    * <p>
550    * A comma-delimited list of all possible user roles.
551    *
552    * <p>
553    * Used in conjunction with {@link #roleGuard()} is used with patterns.
554    *
555    * <h5 class='section'>Example:</h5>
556    * <p class='bjava'>
557    *    <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {
558    *
559    *       <ja>@RestOptions</ja>(
560    *          path=<js>"/foo"</js>,
561    *          rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>,
562    *          roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE &amp;&amp; ROLE_SPECIAL)"</js>
563    *       )
564    *       <jk>public</jk> Object doGet() {
565    *       }
566    *    }
567    * </p>
568    *
569    * <h5 class='section'>See Also:</h5><ul>
570    *    <li class='jm'>{@link org.apache.juneau.rest.RestOpContext.Builder#rolesDeclared(String...)}
571    * </ul>
572    *
573    * @return The annotation value.
574    */
575   String rolesDeclared() default "";
576
577   /**
578    * Specifies the serializers for marshalling POJOs into response bodies for this method.
579    *
580    * <p>
581    * Serializer are used to convert POJOs to HTTP response bodies.
582    * <br>Any of the Juneau framework serializers can be used in this setting.
583    * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method
584    * using a best-match algorithm:
585    * <ul class='javatree'>
586    *    <li class='jm'>{@link Serializer#getMediaTypeRanges()}
587    * </ul>
588    *
589    * <p>
590    * This value overrides serializers specified at the class level using {@link Rest#serializers()}.
591    * The {@link org.apache.juneau.serializer.SerializerSet.Inherit} class can be used to include values from the parent class.
592    *
593    * <h5 class='section'>Example:</h5>
594    * <p class='bjava'>
595    *    <jc>// Define a REST resource that can produce JSON and HTML.</jc>
596    *    <ja>@Rest</ja>(
597    *       serializers={
598    *          JsonParser.<jk>class</jk>,
599    *          HtmlParser.<jk>class</jk>
600    *       }
601    *    )
602    *    <jk>public class</jk> MyResource {
603    *
604    *       <jc>// Define a REST method that can also produce XML.</jc>
605    *       <ja>@RestOptions</ja>(
606    *          parsers={
607    *             SerializerSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk>
608    *          }
609    *       )
610    *       <jk>public</jk> MyBean doGet() {
611    *          ...
612    *       }
613    *    }
614    * </p>
615    *
616    * <p>
617    * The programmatic equivalent to this annotation is:
618    * <p class='bjava'>
619    *    RestOpContext.Builder <jv>builder</jv> = RestOpContext.<jsm>create</jsm>(<jv>method</jv>,<jv>restContext</jv>);
620    *    <jv>builder</jv>.getSerializers().set(<jv>classes</jv>);
621    * </p>
622    *
623    * <h5 class='section'>See Also:</h5><ul>
624    *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Marshalling">Marshalling</a>
625    * </ul>
626    *
627    * @return The annotation value.
628    */
629   Class<? extends Serializer>[] serializers() default {};
630
631   /**
632    * Optional summary for the exposed API.
633    *
634    * <p>
635    * This summary is used in the following locations:
636    * <ul class='spaced-list'>
637    *    <li>
638    *       The value returned by {@link Operation#getSummary()} in the auto-generated swagger.
639    *    <li>
640    *       The <js>"$RS{operationSummary}"</js> variable.
641    *    <li>
642    *       The summary of the method in the Swagger page.
643    * </ul>
644    *
645    * <h5 class='section'>Notes:</h5><ul>
646    *    <li class='note'>
647    *       Corresponds to the swagger field <c>/paths/{path}/{method}/summary</c>.
648    *    <li class='note'>
649    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
650    *       (e.g. <js>"$L{my.localized.variable}"</js>).
651    * </ul>
652    *
653    * @return The annotation value.
654    */
655   String summary() default "";
656
657   /**
658    * Provides swagger-specific metadata on this method.
659    *
660    * <p>
661    * Used to populate the auto-generated OPTIONS swagger documentation.
662    *
663    * <p>
664    * The format of this annotation is JSON when all individual parts are concatenated.
665    * <br>The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional.
666    *
667    * <h5 class='section'>Example:</h5>
668    * <p class='bjava'>
669    *    <ja>@RestOptions</ja>(
670    *       path=<js>"/{propertyName}"</js>,
671    *
672    *       <jc>// Swagger info.</jc>
673    *       swagger={
674    *          <js>"parameters:["</js>,
675    *             <js>"{name:'propertyName',in:'path',description:'The system property name.'},"</js>,
676    *             <js>"{in:'body',description:'The new system property value.'}"</js>,
677    *          <js>"],"</js>,
678    *          <js>"responses:{"</js>,
679    *             <js>"302: {headers:{Location:{description:'The root URL of this resource.'}}},"</js>,
680    *             <js>"403: {description:'User is not an admin.'}"</js>,
681    *          <js>"}"</js>
682    *       }
683    *    )
684    * </p>
685    *
686    * <h5 class='section'>Notes:</h5><ul>
687    *    <li class='note'>
688    *       The format is <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a>.
689    *       <br>Multiple lines are concatenated with newlines.
690    *    <li class='note'>
691    *       The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional.
692    *    <li class='note'>
693    *       These values are superimposed on top of any Swagger JSON file present for the resource in the classpath.
694    *    <li class='note'>
695    *       Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a>
696    *       (e.g. <js>"$L{my.localized.variable}"</js>).
697    * </ul>
698    *
699    * <h5 class='section'>See Also:</h5><ul>
700    *    <li class='ja'>{@link OpSwagger}
701    *    <li class='jc'>{@link SwaggerProvider}
702    * </ul>
703    *
704    * @return The annotation value.
705    */
706   OpSwagger swagger() default @OpSwagger;
707
708   /**
709    * REST method path.
710    *
711    * <p>
712    * Can be used to provide a shortened form for the {@link #path()} value.
713    *
714    * <p>
715    * The following examples are considered equivalent.
716    * <p class='bjava'>
717    *    <jc>// Normal form</jc>
718    *    <ja>@RestOptions</ja>(path=<js>"/{propertyName}"</js>)
719    *
720    *    <jc>// Shortened form</jc>
721    *    <ja>@RestOptions</ja>(<js>"/{propertyName}"</js>)
722    * </p>
723    *
724    * @return The annotation value.
725    */
726   String value() default "";
727}