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.rest.server;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024import org.apache.juneau.bean.swagger.*;
025import org.apache.juneau.commons.*;
026import org.apache.juneau.commons.inject.*;
027import org.apache.juneau.http.remote.*;
028import org.apache.juneau.marshall.encoders.*;
029import org.apache.juneau.marshall.parser.*;
030import org.apache.juneau.marshall.serializer.*;
031import org.apache.juneau.rest.server.converter.*;
032import org.apache.juneau.rest.server.guard.*;
033import org.apache.juneau.rest.server.matcher.*;
034import org.apache.juneau.rest.server.metrics.*;
035import org.apache.juneau.rest.server.servlet.*;
036import org.apache.juneau.rest.server.swagger.*;
037
038/**
039 * Identifies a REST operation Java method on a {@link RestServlet} implementation class.
040 *
041 * <h2 class='section'>See Also:</h2><ul>
042 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestOpAnnotatedMethods">@RestOp-Annotated Method</a>
043
044 * </ul>
045 */
046@Target(METHOD)
047@Retention(RUNTIME)
048@Inherited
049@AnnotationGroup(RestOp.class)
050public @interface RestOp {
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>@RestOp</ja>(method=<jsf>GET</jsf>, 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>@RestOp</ja>(method=<jsf>GET</jsf>, 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>@RestOp</ja>(method=<jsf>GET</jsf>, 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>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>)
089    *    <jk>public</jk> NewPojo newMethod()  {...}
090    *
091    *    <jc>// Call this method if X-Client-Version is at least 1.1, but less than 2.0.</jc>
092    *    <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>)
093    *    <ja>@MarshalledConfig(swaps=NewToOldSwap.<jk>class</jk>)
094    *    <jk>public</jk> NewPojo oldMethod() {
095    *       <jk>return</jk> newMethod();
096    *    }
097    *
098    * <p>
099    * Note that in the previous example, we're returning the exact same POJO, but using a transform to convert it into
100    * an older form.
101    * The old method could also just return back a completely different object.
102    * The range can be any of the following:
103    * <ul>
104    *    <li><js>"[0,1.0)"</js> = Less than 1.0.  1.0 and 1.0.0 does not match.
105    *    <li><js>"[0,1.0]"</js> = Less than or equal to 1.0.  Note that 1.0.1 will match.
106    *    <li><js>"1.0"</js> = At least 1.0.  1.0 and 2.0 will match.
107    * </ul>
108    *
109    * <h4 class='section'>See Also:</h4><ul>
110    *    <li class='ja'>{@link Rest#clientVersionHeader()}
111    * </ul>
112    *
113    * @return The annotation value.
114    */
115   String clientVersion() default "";
116
117   /**
118    * Supported content media types.
119    *
120    * <p>
121    * Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource.
122    *
123    * <h4 class='section'>Notes:</h4><ul>
124    *    <li class='note'>
125    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
126    *       (e.g. <js>"${S:mySystemProperty}"</js>).
127    * </ul>
128    *
129    * <h4 class='section'>See Also:</h4><ul>
130    *    <li class='jm'>{@link RestOpContext#getSupportedContentTypes()}
131    * </ul>
132    *
133    * @return The annotation value.
134    */
135   String[] consumes() default {};
136
137   /**
138    * Class-level response converters.
139    *
140    * <p>
141    * Associates one or more {@link RestConverter converters} with this method.
142    *
143    * @return The annotation value.
144    */
145   Class<? extends RestConverter>[] converters() default {};
146
147   /**
148    * Default <c>Accept</c> header.
149    *
150    * <p>
151    * The default value for the <c>Accept</c> header if not specified on a request.
152    *
153    * <p>
154    * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header.
155    *
156    * @return The annotation value.
157    */
158   String defaultAccept() default "";
159
160   /**
161    * Default character encoding.
162    *
163    * <p>
164    * The default character encoding for the request and response if not specified on the request.
165    *
166    * <h4 class='section'>Notes:</h4><ul>
167    *    <li class='note'>
168    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
169    *       (e.g. <js>"${S:mySystemProperty}"</js>).
170    * </ul>
171    *
172    * <h4 class='section'>See Also:</h4><ul>
173    *    <li class='ja'>{@link Rest#defaultCharset}
174    * </ul>
175    *
176    * @return The annotation value.
177    */
178   String defaultCharset() default "";
179
180   /**
181    * Default <c>Content-Type</c> header.
182    *
183    * <p>
184    * The default value for the <c>Content-Type</c> header if not specified on a request.
185    *
186    * <p>
187    * This is a shortcut for using {@link #defaultRequestHeaders()} for just this specific header.
188    *
189    * @return The annotation value.
190    */
191   String defaultContentType() default "";
192
193   /**
194    * Default request attributes.
195    *
196    * <p>
197    * Specifies default values for request attributes if they're not already set on the request.
198    *
199    * <p>
200    * Affects values returned by the following methods:
201    *    <ul>
202    *       <li class='jm'>{@link RestRequest#getAttribute(String)}.
203    *       <li class='jm'>{@link RestRequest#getAttributes()}.
204    *    </ul>
205    *
206    * <h4 class='section'>Example:</h4>
207    * <p class='bjava'>
208    *    <jc>// Defined via annotation resolving to a config file setting with default value.</jc>
209    *    <ja>@Rest</ja>(defaultRequestAttributes={<js>"Foo=bar"</js>, <js>"Baz: ${C:REST/myAttributeValue}"</js>})
210    *    <jk>public class</jk> MyResource {
211    *
212    *       <jc>// Override at the method level.</jc>
213    *       <ja>@RestGet</ja>(defaultRequestAttributes={<js>"Foo: bar"</js>})
214    *       <jk>public</jk> Object myMethod() {...}
215    *    }
216    * </p>
217    *
218    * <h4 class='section'>Notes:</h4><ul>
219    *    <li class='note'>
220    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
221    *       (e.g. <js>"${L:my.localized.variable}"</js>).
222    * </ul>
223    *
224    * <h4 class='section'>See Also:</h4><ul>
225    *    <li class='ja'>{@link Rest#defaultRequestAttributes()}
226    * </ul>
227    *
228    * @return The annotation value.
229    */
230   String[] defaultRequestAttributes() default {};
231
232   /**
233    * Specifies default values for form-data parameters.
234    *
235    * <p>
236    * Strings are of the format <js>"name=value"</js>.
237    *
238    * <p>
239    * Affects values returned by {@link RestRequest#getFormParam(String)} when the parameter is not present on the
240    * request.
241    *
242    * <h4 class='section'>Example:</h4>
243    * <p class='bjava'>
244    *    <ja>@RestOp</ja>(method=<jsf>POST</jsf>, path=<js>"/*"</js>, defaultRequestFormData={<js>"foo=bar"</js>})
245    *    <jk>public</jk> String doPost(<ja>@FormData</ja>(<js>"foo"</js>) String <jv>foo</jv>)  {...}
246    * </p>
247    *
248    * <h4 class='section'>Notes:</h4><ul>
249    *    <li class='note'>
250    *       You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter.
251    *    <li class='note'>
252    *       Key and value is trimmed of whitespace.
253    *    <li class='note'>
254    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
255    *       (e.g. <js>"${S:mySystemProperty}"</js>).
256    * </ul>
257    *
258    * @return The annotation value.
259    */
260   String[] defaultRequestFormData() default {};
261
262   /**
263    * Default request headers.
264    *
265    * <p>
266    * Specifies default values for request headers if they're not passed in through the request.
267    *
268    * <h4 class='section'>Example:</h4>
269    * <p class='bjava'>
270    *    <jc>// Assume "text/json" Accept value when Accept not specified</jc>
271    *    <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/*"</js>, defaultRequestHeaders={<js>"Accept: text/json"</js>})
272    *    <jk>public</jk> String doGet()  {...}
273    * </p>
274    *
275    * <h4 class='section'>Notes:</h4><ul>
276    *    <li class='note'>
277    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
278    *       (e.g. <js>"${S:mySystemProperty}"</js>).
279    * </ul>
280    *
281    * @return The annotation value.
282    */
283   String[] defaultRequestHeaders() default {};
284
285   /**
286    * Specifies default values for query parameters.
287    *
288    * <p>
289    * Strings are of the format <js>"name=value"</js>.
290    *
291    * <p>
292    * Affects values returned by {@link RestRequest#getQueryParam(String)} when the parameter is not present on the request.
293    *
294    * <h4 class='section'>Example:</h4>
295    * <p class='bjava'>
296    *    <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/*"</js>, defaultRequestQueryData={<js>"foo=bar"</js>})
297    *    <jk>public</jk> String doGet(<ja>@Query</ja>(<js>"foo"</js>) String <jv>foo</jv>)  {...}
298    * </p>
299    *
300    * <h4 class='section'>Notes:</h4><ul>
301    *    <li class='note'>
302    *       You can use either <js>':'</js> or <js>'='</js> as the key/value delimiter.
303    *    <li class='note'>
304    *       Key and value is trimmed of whitespace.
305    *    <li class='note'>
306    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
307    *       (e.g. <js>"${S:mySystemProperty}"</js>).
308    * </ul>
309    *
310    * @return The annotation value.
311    */
312   String[] defaultRequestQueryData() default {};
313
314   /**
315    * Default response headers.
316    *
317    * <p>
318    * Specifies default values for response headers if they're not overwritten during the request.
319    *
320    * <h4 class='section'>Example:</h4>
321    * <p class='bjava'>
322    *    <jc>// Assume "text/json" Accept value when Accept not specified</jc>
323    *    <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/*"</js>, defaultResponseHeaders={<js>"Content-Type: text/json"</js>})
324    *    <jk>public</jk> String doGet()  {...}
325    * </p>
326    *
327    * <h4 class='section'>Notes:</h4><ul>
328    *    <li class='note'>
329    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
330    *       (e.g. <js>"${S:mySystemProperty}"</js>).
331    * </ul>
332    *
333    * @return The annotation value.
334    */
335   String[] defaultResponseHeaders() default {};
336
337   /**
338    * Optional description for the exposed API.
339    *
340    * <p>
341    * This description is used in the following locations:
342    * <ul class='spaced-list'>
343    *    <li>
344    *       The value returned by {@link Operation#getDescription()} in the auto-generated swagger.
345    *    <li>
346    *       The <js>"${RS:operationDescription}"</js> variable.
347    *    <li>
348    *       The description of the method in the Swagger page.
349    * </ul>
350    *
351    * <h4 class='section'>Notes:</h4><ul>
352    *    <li class='note'>
353    *       Corresponds to the swagger field <c>/paths/{path}/{method}/description</c>.
354    *    <li class='note'>
355    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
356    *       (e.g. <js>"${L:my.localized.variable}"</js>).
357    * </ul>
358    *
359    * @return The annotation value.
360    */
361   String[] description() default {};
362
363   /**
364    * Specifies the compression encoders for this method.
365    *
366    * <p>
367    * Encoders are used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses.
368    *
369    * <p>
370    * This value overrides encoders specified at the class level using {@link Rest#encoders()}.
371    * The {@link org.apache.juneau.marshall.encoders.EncoderSet.Inherit EncoderSet.Inherit} class can be used to include values from the parent class.
372    *
373    * <h4 class='section'>Example:</h4>
374    * <p class='bjava'>
375    *    <jc>// Define a REST resource that handles GZIP compression.</jc>
376    *    <ja>@Rest</ja>(
377    *       encoders={
378    *          GzipEncoder.<jk>class</jk>
379    *       }
380    *    )
381    *    <jk>public class</jk> MyResource {
382    *
383    *       <jc>// Define a REST method that can also use a custom encoder.</jc>
384    *       <ja>@RestOp</ja>(
385    *          method=<jsf>GET</jsf>,
386    *          encoders={
387    *             EncoderSet.Inherit.<jk>class</jk>, MyEncoder.<jk>class</jk>
388    *          }
389    *       )
390    *       <jk>public</jk> MyBean doGet() {
391    *          ...
392    *       }
393    *    }
394    * </p>
395    *
396    * <p>
397    * For programmatic equivalents, contribute a {@link EncoderSet} bean via
398    * {@link Bean @Bean(name="encoders")} (use methodScope to scope to specific operation methods).
399    *
400    * <h4 class='section'>See Also:</h4><ul>
401    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerEncoders">Encoders in REST servers</a>
402    * </ul>
403    *
404    * @return The annotation value.
405    */
406   Class<? extends Encoder>[] encoders() default {};
407
408   /**
409    * Method-level guards.
410    *
411    * <p>
412    * Associates one or more {@link RestGuard RestGuards} with this method.
413    *
414    * @return The annotation value.
415    */
416   Class<? extends RestGuard>[] guards() default {};
417
418   /**
419    * Method matchers.
420    *
421    * <p>
422    * Associates one more more {@link RestMatcher RestMatchers} with this method.
423    *
424    * <p>
425    * Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but
426    * differing based on some request attribute, such as a specific header value.
427    *
428    * <h4 class='section'>See Also:</h4><ul>
429    *    <li class='jac'>{@link RestMatcher}
430    * </ul>
431    *
432    * @return The annotation value.
433    */
434   Class<? extends RestMatcher>[] matchers() default {};
435
436   /**
437    * The maximum allowed input size (in bytes) on HTTP requests.
438    *
439    * <p>
440    * Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting
441    * in out-of-memory errors which could affect system stability.
442    *
443    * <h4 class='section'>Example:</h4>
444    * <p class='bjava'>
445    *    <ja>@RestOp</ja>(
446    *       maxInput=<js>"10M"</js>
447    *    )
448    * </p>
449    *
450    * <h4 class='section'>Notes:</h4><ul>
451    *    <li>
452    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
453    *       (e.g. <js>"${S:mySystemProperty}"</js>).
454    * </ul>
455    *
456    * <h4 class='section'>See Also:</h4><ul>
457    *    <li class='ja'>{@link Rest#maxInput}
458    * </ul>
459    *
460    * @return The annotation value.
461    */
462   String maxInput() default "";
463
464   /**
465    * REST method name.
466    *
467    * <p>
468    * Typically <js>"GET"</js>, <js>"PUT"</js>, <js>"POST"</js>, <js>"DELETE"</js>, or <js>"OPTIONS"</js>.
469    *
470    * <p>
471    * Method names are case-insensitive (always folded to upper-case).
472    *
473    * <p>
474    * Note that you can use {@link org.apache.juneau.http.HttpMethod} for constant values.
475    *
476    * <p>
477    * Note that you can also use {@link #value()} to specify the method name and path in shortened form.
478    *
479    * <p>
480    * Besides the standard HTTP method names, the following can also be specified:
481    * <ul class='spaced-list'>
482    *    <li>
483    *       <js>"*"</js>
484    *       - Denotes any method.
485    *       <br>Use this if you want to capture any HTTP methods in a single Java method.
486    *       <br>The {@link Method @Method} annotation and/or {@link RestRequest#getMethod()} method can be used to
487    *       distinguish the actual HTTP method name.
488    *    <li>
489    *       <js>""</js>
490    *       - Auto-detect.
491    *       <br>The method name is determined based on the Java method name.
492    *       <br>For example, if the method is <c>doPost(...)</c>, then the method name is automatically detected
493    *       as <js>"POST"</js>.
494    *       <br>Otherwise, defaults to <js>"GET"</js>.
495    *    <li>
496    *       <js>"RRPC"</js>
497    *       - Remote-proxy interface.
498    *       <br>This denotes a Java method that returns an object (usually an interface, often annotated with the
499    *       {@link Remote @Remote} annotation) to be used as a remote proxy using
500    *       <c>RestClient.getRemoteInterface(Class&lt;T&gt; interfaceClass, String url)</c>.
501    *       <br>This allows you to construct client-side interface proxies using REST as a transport medium.
502    *       <br>Conceptually, this is simply a fancy <c>POST</c> against the url <js>"/{path}/{javaMethodName}"</js>
503    *       where the arguments are marshalled from the client to the server as an HTTP content containing an array of
504    *       objects, passed to the method as arguments, and then the resulting object is marshalled back to the client.
505    *    <li>
506    *       Anything else
507    *       - Overloaded non-HTTP-standard names that are passed in through a <c>&amp;method=methodName</c> URL
508    *       parameter.
509    *       <br>On a safe request (<c>GET</c>, <c>HEAD</c>, <c>OPTIONS</c>, <c>TRACE</c>), only when the operation is
510    *       declared {@link #read() read=true}.
511    * </ul>
512    *
513    * @return The annotation value.
514    */
515   String method() default "";
516
517   /**
518    * Specifies the parsers for converting HTTP request bodies into POJOs for this method.
519    *
520    * <p>
521    * Parsers are used to convert the content of HTTP requests into POJOs.
522    * <br>Any of the Juneau framework parsers can be used in this setting.
523    * <br>The parser selected is based on the request <c>Content-Type</c> header matched against the values returned by the following method
524    * using a best-match algorithm:
525    * <ul class='javatree'>
526    *    <li class='jm'>{@link Parser#getMediaTypes()}
527    * </ul>
528    *
529    * <p>
530    * This value overrides parsers specified at the class level using {@link Rest#parsers()}.
531    * The {@link org.apache.juneau.marshall.parser.ParserSet.Inherit ParserSet.Inherit} class can be used to include values from the parent class.
532    *
533    * <h4 class='section'>Example:</h4>
534    * <p class='bjava'>
535    *    <jc>// Define a REST resource that can consume JSON and HTML.</jc>
536    *    <ja>@Rest</ja>(
537    *       parsers={
538    *          JsonParser.<jk>class</jk>,
539    *          HtmlParser.<jk>class</jk>
540    *       }
541    *    )
542    *    <jk>public class</jk> MyResource {
543    *
544    *       <jc>// Define a REST method that can also consume XML.</jc>
545    *       <ja>@RestOp</ja>(
546    *          method=<jsf>POST</jsf>,
547    *          parsers={
548    *             ParserSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk>
549    *          }
550    *       )
551    *       <jk>public void</jk> doPost(MyBean <jv>bean</jv>) {
552    *          ...
553    *       }
554    *    }
555    * </p>
556    *
557    * <p>
558    * For programmatic equivalents, contribute a {@link ParserSet} bean via
559    * {@link Bean @Bean(name="parsers")} (use methodScope to scope to specific operation methods).
560    *
561    * <h4 class='section'>See Also:</h4><ul>
562    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a>
563    * </ul>
564    *
565    * @return The annotation value.
566    */
567   Class<?>[] parsers() default {};
568
569   /**
570    * Optional path pattern for the specified method.
571    *
572    * <p>
573    * Appending <js>"/*"</js> to the end of the path pattern will make it match any remainder too.
574    * <br>Not appending <js>"/*"</js> to the end of the pattern will cause a 404 (Not found) error to occur if the exact
575    * pattern is not found.
576    *
577    * <p>
578    * The path can contain variables that get resolved to {@link org.apache.juneau.http.Path @Path} parameters.
579    *
580    * <h4 class='figure'>Examples:</h4>
581    * <p class='bjava'>
582    *    <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
583    * </p>
584    * <p class='bjava'>
585    *    <ja>@RestOp</ja>(method=<jsf>GET</jsf>, path=<js>"/myurl/{0}/{1}/{2}/*"</js>)
586    * </p>
587    *
588    * <p>
589    * If you do not specify a path name, then the path name is inferred from the Java method name.
590    *
591    * <h4 class='figure'>Example:</h4>
592    * <p class='bjava'>
593    *    <jc>// Path is assumed to be "/foo".</jc>
594    *    <ja>@RestOp</ja>(method=<jsf>GET</jsf>)
595    *    <jk>public void</jk> foo() {...}
596    * </p>
597    *
598    * <p>
599    * If you also do not specify the {@link #method()} and the Java method name starts with <js>"get"</js>, <js>"put"</js>, <js>"post"</js>, or <js>"delete"</js>,
600    * then the HTTP method name is stripped from the inferred path.
601    *
602    * <h4 class='figure'>Examples:</h4>
603    * <p class='bjava'>
604    *    <jc>// Method is GET, path is "/foo".</jc>
605    *    <ja>@RestOp</ja>
606    *    <jk>public void</jk> getFoo() {...}
607    * </p>
608    * <p class='bjava'>
609    *    <jc>// Method is DELETE, path is "/bar".</jc>
610    *    <ja>@RestOp</ja>
611    *    <jk>public void</jk> deleteBar() {...}
612    * </p>
613    * <p class='bjava'>
614    *    <jc>// Method is GET, path is "/foobar".</jc>
615    *    <ja>@RestOp</ja>
616    *    <jk>public void</jk> foobar() {...}
617    * </p>
618    * <p class='bjava'>
619    *    <jc>// Method is GET, path is "/".</jc>
620    *    <ja>@RestOp</ja>
621    *    <jk>public void</jk> get() {...}
622    * </p>
623    *
624    * <p>
625    * Note that you can also use {@link #value()} to specify the method name and path in shortened form.
626    *
627    * <h4 class='section'>See Also:</h4><ul>
628    *    <li class='ja'>{@link org.apache.juneau.http.Path}
629    * </ul>
630    *
631    * @return The annotation value.
632    */
633   String[] path() default {};
634
635   /**
636    * Per-operation override for {@link Rest#problemDetails() @Rest(problemDetails)}.
637    *
638    * <p>
639    * When set on a {@code @RestOp} method, this value takes precedence over the resource-level
640    * {@code @Rest(problemDetails)} attribute for this operation. Tri-state semantics:
641    *
642    * <ul class='values'>
643    *    <li><js>"true"</js> &mdash; enable problem-details responses for this operation.
644    *    <li><js>"false"</js> &mdash; disable problem-details responses for this operation (overrides an
645    *       opted-in resource).
646    *    <li><js>""</js> (default) &mdash; inherit from {@link Rest#problemDetails()}.
647    * </ul>
648    *
649    * <h4 class='section'>Notes:</h4><ul>
650    *    <li class='note'>
651    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
652    *       (e.g. <js>"${L:my.localized.variable}"</js>).
653    * </ul>
654    *
655    * <h4 class='section'>See Also:</h4><ul>
656    *    <li class='ja'>{@link Rest#problemDetails()}
657    * </ul>
658    *
659    * @return The annotation value.
660    */
661   String problemDetails() default "";
662
663   /**
664    * Per-operation override for {@link Rest#debugMarshalling() @Rest(debugMarshalling)}.
665    *
666    * <p>
667    * When set on a {@code @RestOp} method, this value takes precedence over the resource-level
668    * {@code @Rest(debugMarshalling)} attribute for this operation. Tri-state semantics:
669    *
670    * <ul class='values'>
671    *    <li><js>"true"</js> &mdash; enable marshalling debug for this operation.
672    *    <li><js>"false"</js> &mdash; disable marshalling debug for this operation (overrides an opted-in resource).
673    *    <li><js>""</js> (default) &mdash; inherit from {@link Rest#debugMarshalling()}.
674    * </ul>
675    *
676    * <h4 class='section'>Notes:</h4><ul>
677    *    <li class='note'>
678    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>.
679    * </ul>
680    *
681    * <h4 class='section'>See Also:</h4><ul>
682    *    <li class='ja'>{@link Rest#debugMarshalling()}
683    * </ul>
684    *
685    * @return The annotation value.
686    */
687   String debugMarshalling() default "";
688
689   /**
690    * Per-operation override for {@link Rest#virtualThreads() @Rest(virtualThreads)}.
691    *
692    * <p>
693    * When set, this value takes precedence over the resource-level setting for this operation. Tri-state
694    * semantics:
695    *
696    * <ul class='values'>
697    *    <li><js>"true"</js> &mdash; enable virtual-thread dispatch for this operation (Java 21+ only;
698    *       gracefully ignored on older JVMs).
699    *    <li><js>"false"</js> &mdash; disable virtual-thread dispatch for this operation (overrides an
700    *       opted-in resource).
701    *    <li><js>""</js> (default) &mdash; inherit from {@link Rest#virtualThreads()}.
702    * </ul>
703    *
704    * <h4 class='section'>Notes:</h4><ul>
705    *    <li class='note'>
706    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
707    *       (e.g. <js>"${E:ENABLE_VT:false}"</js>).
708    * </ul>
709    *
710    * <h4 class='section'>See Also:</h4><ul>
711    *    <li class='ja'>{@link Rest#virtualThreads()}
712    * </ul>
713    *
714    * @return The annotation value.
715    */
716   String virtualThreads() default "";
717
718   /**
719    * Per-operation observability opt-in / opt-out control.
720    *
721    * <p>
722    * Overrides the resource-level {@link Rest#observability()} setting for this specific operation.
723    * Controls whether the observability block ({@link MetricsRecorder} /
724    * {@link org.apache.juneau.rest.server.tracing.TracerHook}) fires for this operation.
725    *
726    * <ul class='values'>
727    *    <li><js>"true"</js> &mdash; strict opt-in: this operation <em>requires</em> a wired observability backend.
728    *       If neither a {@code @Bean MetricsRecorder} nor a {@code @Bean TracerHook} is registered when the
729    *       {@link RestContext} is built, construction fails with a precise error.
730    *    <li><js>"false"</js> &mdash; explicit opt-out: the observability block is short-circuited for this operation,
731    *       even when a wired backend is present. Also suppresses
732    *       {@link org.apache.juneau.rest.server.tracing.TraceContextResponseProcessor} header injection.
733    *    <li><js>""</js> (default) &mdash; inherits the resource-level {@link Rest#observability()} setting.
734    *       If the resource-level setting is also empty, uses the existing behavior: the observability block
735    *       runs per-op, but a missing backend silently falls back to the NoOp singleton.
736    * </ul>
737    *
738    * <h4 class='section'>Notes:</h4><ul>
739    *    <li class='note'>
740    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
741    *       (e.g. <js>"${E:ENABLE_OP_OBSERVABILITY:false}"</js>).
742    *    <li class='note'>
743    *       This per-operation setting takes full precedence over {@link Rest#observability()}.
744    * </ul>
745    *
746    * <h4 class='section'>See Also:</h4><ul>
747    *    <li class='ja'>{@link Rest#observability()}
748    *    <li class='jc'>{@link MetricsRecorder}
749    *    <li class='jc'>{@link org.apache.juneau.rest.server.tracing.TracerHook}
750    * </ul>
751    *
752    * @return The annotation value.
753    * @since 10.0.0
754    */
755   String observability() default "";
756
757   /**
758    * Per-operation metric name override.
759    *
760    * <p>
761    * Overrides the metric name passed to {@link MetricsRecorder#record(String, String, String, int, java.time.Duration, Throwable, String, String) record()}
762    * for this operation.  When empty (default), the recorder uses its own default name derivation (typically the
763    * fully-qualified operation name).
764    *
765    * <h4 class='section'>Notes:</h4><ul>
766    *    <li class='note'>
767    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>.
768    *    <li class='note'>
769    *       Has no effect when observability is disabled for this operation.
770    * </ul>
771    *
772    * @return The annotation value.
773    * @since 10.0.0
774    */
775   String metricName() default "";
776
777   /**
778    * Per-operation metric tags.
779    *
780    * <p>
781    * Additional metric tags to pass to {@link MetricsRecorder#record(String, String, String, int, java.time.Duration, Throwable, String, String) record()}.
782    * Format: comma-separated {@code key=value} pairs, e.g. {@code "team=payments,region=us-east"}.
783    * When empty (default), no additional tags are passed.
784    *
785    * <h4 class='section'>Notes:</h4><ul>
786    *    <li class='note'>
787    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>.
788    *    <li class='note'>
789    *       The recorder implementation is responsible for parsing the comma-separated {@code key=value} string.
790    *    <li class='note'>
791    *       Has no effect when observability is disabled for this operation.
792    * </ul>
793    *
794    * @return The annotation value.
795    * @since 10.0.0
796    */
797   String metricTags() default "";
798
799   /**
800    * Per-operation override for {@link Rest#asyncTimeoutMillis() @Rest(asyncTimeoutMillis)}.
801    *
802    * <p>
803    * Configurable timeout (milliseconds) applied to {@link java.util.concurrent.CompletableFuture}-returning
804    * handlers. Default is 30,000 ms inherited from the resource. Set to {@code "0"} to disable the timeout.
805    *
806    * <h4 class='section'>Notes:</h4><ul>
807    *    <li class='note'>
808    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>.
809    * </ul>
810    *
811    * <h4 class='section'>See Also:</h4><ul>
812    *    <li class='ja'>{@link Rest#asyncTimeoutMillis()}
813    * </ul>
814    *
815    * @return The annotation value.
816    */
817   String asyncTimeoutMillis() default "";
818
819   /**
820    * Per-operation override for {@link Rest#asyncCompletionExecutor() @Rest(asyncCompletionExecutor)}.
821    *
822    * <p>
823    * Names the {@link java.util.concurrent.Executor} bean used to route completion callbacks for this
824    * specific operation through a dedicated thread pool. Empty string (default) inherits from
825    * {@link Rest#asyncCompletionExecutor()}.
826    *
827    * <h4 class='section'>See Also:</h4><ul>
828    *    <li class='ja'>{@link Rest#asyncCompletionExecutor()}
829    * </ul>
830    *
831    * @return The annotation value.
832    * @since 10.0.0
833    */
834   String asyncCompletionExecutor() default "";
835
836   /**
837    * Supported accept media types.
838    *
839    * <p>
840    * Overrides the media types inferred from the serializers that identify what media types can be produced by the resource.
841    *
842    * <h4 class='section'>Notes:</h4><ul>
843    *    <li class='note'>
844    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
845    *       (e.g. <js>"${S:mySystemProperty}"</js>).
846    * </ul>
847    *
848    * <h4 class='section'>See Also:</h4><ul>
849    *    <li class='jm'>{@link RestOpContext#getSupportedAcceptTypes()}
850    * </ul>
851    *
852    * @return The annotation value.
853    */
854   String[] produces() default {};
855
856   /**
857    * Allowed serializer session option keys for this operation (ordered merge, prefix {@code -key} removes a key).
858    *
859    * <p>
860    * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Serializer-Options"</js>
861    * header or <js>"juneauSerializerOptions"</js> query parameter.
862    * Merged on top of resource-level {@link Rest#allowedSerializerOptions()} values.
863    * Use {@link #noInherit()} to replace rather than extend the resource-level list.
864    *
865    * <h4 class='section'>See Also:</h4><ul>
866    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a>
867    * </ul>
868    *
869    * @return The annotation value.
870    */
871   String[] allowedSerializerOptions() default {};
872
873   /**
874    * Allowed parser session option keys for this operation (ordered merge, prefix {@code -key} removes a key).
875    *
876    * <p>
877    * Comma-delimited list of session property keys that clients may send via the <js>"X-Juneau-Parser-Options"</js>
878    * header or <js>"juneauParserOptions"</js> query parameter.
879    * Merged on top of resource-level {@link Rest#allowedParserOptions()} values.
880    * Use {@link #noInherit()} to replace rather than extend the resource-level list.
881    *
882    * <h4 class='section'>See Also:</h4><ul>
883    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions#safe-properties">Safe Properties</a>
884    * </ul>
885    *
886    * @return The annotation value.
887    */
888   String[] allowedParserOptions() default {};
889
890   /**
891    * Property names for which less-derived contributions are NOT inherited.
892    *
893    * <p>
894    * Accepted values: {@code "allowedSerializerOptions"}, {@code "allowedParserOptions"},
895    * {@code "problemDetails"}, {@code "debugMarshalling"}.
896    * Prevents the named property from inheriting values from the enclosing {@code @Rest} annotation.
897    * The {@code noInherit} attribute itself is never inherited.
898    *
899    * <h4 class='section'>See Also:</h4><ul>
900    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SessionOptions">Session Options via HTTP</a>
901    * </ul>
902    *
903    * @return The annotation value.
904    */
905   String[] noInherit() default {};
906
907   /**
908    * Declares that this operation's custom method is a read.
909    *
910    * <p>
911    * A request whose request line is safe (<c>GET</c>, <c>HEAD</c>, <c>OPTIONS</c> or <c>TRACE</c>) may be overridden
912    * (through the {@code method} query parameter or an override header, see {@link Rest#allowedMethodParams()} and
913    * {@link Rest#allowedMethodHeaders()}) only to another safe method, or to the method of an operation declared
914    * <c>read=<jk>true</jk></c>.  Any other override of a safe request is refused with <c>405 Method Not Allowed</c>,
915    * so a link, a crawler or a prefetcher following a plain <c>GET</c> can never reach an operation that changes state.
916    *
917    * <h4 class='section'>Example:</h4>
918    * <p class='bjava'>
919    *    <jc>// Reachable as GET /files/foo.txt?method=VIEW, as well as VIEW /files/foo.txt.</jc>
920    *    <ja>@RestOp</ja>(method=<js>"VIEW"</js>, path=<js>"/files/*"</js>, read=<jk>true</jk>)
921    *    <jk>public</jk> Reader view(...) {...}
922    * </p>
923    *
924    * <p>
925    * The declaration is the developer's promise that the operation does not change state, exactly as <c>GET</c>
926    * promises.  Nothing can verify it.  {@link Mutating @Mutating} is the opposite promise.
927    *
928    * <h4 class='section'>Notes:</h4><ul>
929    *    <li class='note'>
930    *       The attribute is read from the annotation that supplies the operation's method (or, when the method is
931    *       inferred from the Java method name, from the nearest <ja>@RestOp</ja>).  A subclass that re-declares the method
932    *       therefore also re-declares whether it is a read: <c>read=<jk>true</jk></c> on an overridden annotation that
933    *       names its own method is replaced along with that method.  <c>read=<jk>true</jk></c> on another
934    *       <ja>@RestOp</ja> in the chain that names no method would be silently ignored, so it fails the resource when
935    *       its operations are assembled.
936    *    <li class='note'>
937    *       <c>read=<jk>true</jk></c> fails the resource when the method is <c>POST</c>, <c>PUT</c>, <c>PATCH</c>,
938    *       <c>DELETE</c>, <c>CONNECT</c>, <js>"*"</js> or <js>"RRPC"</js>, or when the Java method is also
939    *       {@link Mutating @Mutating}.  On a safe method it is redundant and has no effect.
940    *    <li class='note'>
941    *       A CSRF or loopback boundary filter still judges a request on the method it claims, so behind a boundary a
942    *       <c>GET ?method=VIEW</c> is treated as a write.  Prefer path-based links (<c>/view/{file}</c>) for reads.
943    * </ul>
944    *
945    * <h4 class='section'>See Also:</h4><ul>
946    *    <li class='ja'>{@link Mutating}
947    *    <li class='jm'>{@link MethodSafety#check(java.util.List)}
948    * </ul>
949    *
950    * @return The annotation value.
951    * @since 10.0.0
952    */
953   boolean read() default false;
954
955   /**
956    * Role guard.
957    *
958    * <p>
959    * An expression defining if a user with the specified roles are allowed to access this method.
960    *
961    * <h4 class='section'>Example:</h4>
962    * <p class='bjava'>
963    *    <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {
964    *
965    *       <ja>@RestOp</ja>(
966    *          method=<jsf>GET</jsf>,
967    *          path=<js>"/foo"</js>,
968    *          roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE &amp;&amp; ROLE_SPECIAL)"</js>
969    *       )
970    *       <jk>public</jk> Object doGet() {
971    *       }
972    *    }
973    * </p>
974    *
975    * <h4 class='section'>Notes:</h4><ul>
976    *    <li class='note'>
977    *       Supports any of the following expression constructs:
978    *       <ul>
979    *          <li><js>"foo"</js> - Single arguments.
980    *          <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments.
981    *          <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax.
982    *          <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax.
983    *          <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>.
984    *          <li><js>"fo* &amp; *oo"</js> - Multiple AND'ed arguments, ampersand syntax.
985    *          <li><js>"fo* &amp;&amp; *oo"</js> - Multiple AND'ed arguments, Java-AND syntax.
986    *          <li><js>"fo* || (*oo || bar)"</js> - Parenthesis.
987    *       </ul>
988    *    <li class='note'>
989    *       AND operations take precedence over OR operations (as expected).
990    *    <li class='note'>
991    *       Whitespace is ignored.
992    *    <li class='note'>
993    *       <jk>null</jk> or empty expressions always match as <jk>false</jk>.
994    *    <li class='note'>
995    *       If patterns are used, you must specify the list of declared roles using {@link #rolesDeclared()}.
996    *    <li class='note'>
997    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
998    *       (e.g. <js>"${L:my.localized.variable}"</js>).
999    *    <li class='note'>
1000    *       When defined on parent/child classes and methods, ALL guards within the hierarchy must pass.
1001    * </ul>
1002    *
1003    * @return The annotation value.
1004    */
1005   String roleGuard() default "";
1006
1007   /**
1008    * Declared roles.
1009    *
1010    * <p>
1011    * A comma-delimited list of all possible user roles.
1012    *
1013    * <p>
1014    * Used in conjunction with {@link #roleGuard()} is used with patterns.
1015    *
1016    * <h4 class='section'>Example:</h4>
1017    * <p class='bjava'>
1018    *    <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {
1019    *
1020    *       <ja>@RestOp</ja>(
1021    *          method=<jsf>GET</jsf>,
1022    *          path=<js>"/foo"</js>,
1023    *          rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>,
1024    *          roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE &amp;&amp; ROLE_SPECIAL)"</js>
1025    *       )
1026    *       <jk>public</jk> Object doGet() {
1027    *       }
1028    *    }
1029    * </p>
1030    *
1031    * @return The annotation value.
1032    */
1033   String rolesDeclared() default "";
1034
1035   /**
1036    * Specifies the serializers for marshalling POJOs into response bodies for this method.
1037    *
1038    * <p>
1039    * Serializer are used to convert POJOs to HTTP response bodies.
1040    * <br>Any of the Juneau framework serializers can be used in this setting.
1041    * <br>The serializer selected is based on the request <c>Accept</c> header matched against the values returned by the following method
1042    * using a best-match algorithm:
1043    * <ul class='javatree'>
1044    *    <li class='jm'>{@link Serializer#getMediaTypeRanges()}
1045    * </ul>
1046    *
1047    * <p>
1048    * This value overrides serializers specified at the class level using {@link Rest#serializers()}.
1049    * The {@link org.apache.juneau.marshall.serializer.SerializerSet.Inherit SerializerSet.Inherit} class can be used to include values from the parent class.
1050    *
1051    * <h4 class='section'>Example:</h4>
1052    * <p class='bjava'>
1053    *    <jc>// Define a REST resource that can produce JSON and HTML.</jc>
1054    *    <ja>@Rest</ja>(
1055    *       serializers={
1056    *          JsonParser.<jk>class</jk>,
1057    *          HtmlParser.<jk>class</jk>
1058    *       }
1059    *    )
1060    *    <jk>public class</jk> MyResource {
1061    *
1062    *       <jc>// Define a REST method that can also produce XML.</jc>
1063    *       <ja>@RestOp</ja>(
1064    *          method=<jsf>POST</jsf>,
1065    *          parsers={
1066    *             SerializerSet.Inherit.<jk>class</jk>, XmlParser.<jk>class</jk>
1067    *          }
1068    *       )
1069    *       <jk>public void</jk> doPost(MyBean <jv>bean</jv>) {
1070    *          ...
1071    *       }
1072    *    }
1073    * </p>
1074    *
1075    * <p>
1076    * For programmatic equivalents, contribute a {@link SerializerSet} bean via
1077    * {@link Bean @Bean(name="serializers")} (use methodScope to scope to specific operation methods).
1078    *
1079    * <h4 class='section'>See Also:</h4><ul>
1080    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshalling">Marshalling</a>
1081    * </ul>
1082    *
1083    * @return The annotation value.
1084    */
1085   Class<? extends Serializer>[] serializers() default {};
1086
1087   /**
1088    * Optional summary for the exposed API.
1089    *
1090    * <p>
1091    * This summary is used in the following locations:
1092    * <ul class='spaced-list'>
1093    *    <li>
1094    *       The value returned by {@link Operation#getSummary()} in the auto-generated swagger.
1095    *    <li>
1096    *       The <js>"${RS:operationSummary}"</js> variable.
1097    *    <li>
1098    *       The summary of the method in the Swagger page.
1099    * </ul>
1100    *
1101    * <h4 class='section'>Notes:</h4><ul>
1102    *    <li class='note'>
1103    *       Corresponds to the swagger field <c>/paths/{path}/{method}/summary</c>.
1104    *    <li class='note'>
1105    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
1106    *       (e.g. <js>"${L:my.localized.variable}"</js>).
1107    * </ul>
1108    *
1109    * @return The annotation value.
1110    */
1111   String summary() default "";
1112
1113   /**
1114    * Provides swagger-specific metadata on this method.
1115    *
1116    * <p>
1117    * Used to populate the auto-generated OPTIONS swagger documentation.
1118    *
1119    * <p>
1120    * The format of this annotation is JSON when all individual parts are concatenated.
1121    * <br>The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional.
1122    *
1123    * <h4 class='section'>Example:</h4>
1124    * <p class='bjava'>
1125    *    <ja>@RestOp</ja>(
1126    *       method=<jsf>PUT</jsf>,
1127    *       path=<js>"/{propertyName}"</js>,
1128    *
1129    *       <jc>// Swagger info.</jc>
1130    *       swagger={
1131    *          <js>"parameters:["</js>,
1132    *             <js>"{name:'propertyName',in:'path',description:'The system property name.'},"</js>,
1133    *             <js>"{in:'body',description:'The new system property value.'}"</js>,
1134    *          <js>"],"</js>,
1135    *          <js>"responses:{"</js>,
1136    *             <js>"302: {headers:{Location:{description:'The root URL of this resource.'}}},"</js>,
1137    *             <js>"403: {description:'User is not an admin.'}"</js>,
1138    *          <js>"}"</js>
1139    *       }
1140    *    )
1141    * </p>
1142    *
1143    * <h4 class='section'>Notes:</h4><ul>
1144    *    <li class='note'>
1145    *       The format is <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>.
1146    *       <br>Multiple lines are concatenated with newlines.
1147    *    <li class='note'>
1148    *       The starting and ending <js>'{'</js>/<js>'}'</js> characters around the entire value are optional.
1149    *    <li class='note'>
1150    *       These values are superimposed on top of any Swagger JSON file present for the resource in the classpath.
1151    *    <li class='note'>
1152    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
1153    *       (e.g. <js>"${L:my.localized.variable}"</js>).
1154    * </ul>
1155    *
1156    * <h4 class='section'>See Also:</h4><ul>
1157    *    <li class='ja'>{@link OpSwagger}
1158    *    <li class='jc'>{@link SwaggerProvider}
1159    * </ul>
1160    *
1161    * @return The annotation value.
1162    */
1163   OpSwagger swagger() default @OpSwagger;
1164
1165   /**
1166    * REST method name and path.
1167    *
1168    * <p>
1169    * Can be used to provide a shortened combined form for the {@link #method()} and {@link #path()} values.
1170    *
1171    * <p>
1172    * The following examples are considered equivalent.
1173    * <p class='bjava'>
1174    *    <jc>// Normal form</jc>
1175    *    <ja>@RestOp</ja>(method=<jsf>PUT</jsf>, path=<js>"/{propertyName}"</js>)
1176    *
1177    *    <jc>// Shortened form</jc>
1178    *    <ja>@RestOp</ja>(<js>"PUT /{propertyName}"</js>)
1179    * </p>
1180    *
1181    * <h4 class='section'>Notes:</h4><ul>
1182    *    <li class='note'>
1183    *       The path portion is optional.
1184    * </ul>
1185    *
1186    * @return The annotation value.
1187    */
1188   String value() default "";
1189}