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.http;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024import org.apache.juneau.commons.*;
025
026/**
027 * REST response annotation.
028 *
029 * <p>
030 * Identifies an interface to use to interact with HTTP parts of an HTTP response through a bean.
031 *
032 * <p>
033 * Can be used in the following locations:
034 *  <ul>
035 *    <li>Exception classes thrown from server-side <ja>@RestOp</ja>-annotated methods.
036 *    <li>Return type classes of server-side <ja>@RestOp</ja>-annotated methods.
037 *    <li>Arguments and argument-types of server-side <ja>@RestOp</ja>-annotated methods.
038 *    <li>Return type classes of server-side <ja>@RemoteOp</ja>-annotated methods.
039 *    <li>Client-side <ja>@RemoteOp</ja>-annotated methods.
040 *    <li>Return type interfaces of client-side <ja>@RemoteOp</ja>-annotated methods.
041 * </ul>
042 *
043 * <h5 class='section'>See Also:</h5><ul>
044 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Response">@Response</a>
045 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>
046 *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#responseObject">Swagger Response Object</a>
047 * </ul>
048 */
049@Documented
050@Target({ PARAMETER, TYPE, METHOD })
051@Retention(RUNTIME)
052@Inherited
053public @interface Response {
054
055   /**
056    * Optional description for the exposed API.
057    *
058    * @return The annotation value.
059    * @since 9.2.0
060    */
061   String[] description() default {};
062
063   /**
064    * Short, concise summary of the exposed API.
065    *
066    * <p>
067    * Intended as a brief, single-line description suitable for AI/LLM consumption, compact documentation,
068    * or any context where brevity matters. See {@link Schema#summary()}
069    * for the canonical definition.
070    *
071    * @return The annotation value.
072    * @since 10.0.0
073    */
074   String summary() default "";
075
076   /**
077    * Serialized examples of the body of a response.
078    *
079    * <p>
080    * This is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object whose keys are media types and values are string representations of that value.
081    *
082    * <p class='bjava'>
083    *    <jc>// A JSON representation of a PetCreate object.</jc>
084    *    <ja>@Response</ja>(
085    *       examples={
086    *          <js>"'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',"</js>,
087    *          <js>"'text/uon':'(name:Doggie,species=Dog)'"</js>
088    *       }
089    *    )
090    * </p>
091    *
092    * <h5 class='section'>Used for:</h5>
093    * <ul class='spaced-list'>
094    *    <li>
095    *       Server-side generated Swagger documentation.
096    * </ul>
097    *
098    * <h5 class='section'>Notes:</h5><ul>
099    *    <li class='note'>
100    *       The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object with string keys (media type) and string values (example for that media type) .
101    *    <li class='note'>
102    *       The leading/trailing <c>{ }</c> characters are optional.
103    *    <li class='note'>
104    *       Multiple lines are concatenated with newlines so that you can format the value to be readable:
105    *    <li class='note'>
106    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>) for the swagger generator.
107    *    <li class='note'>
108    *       Resolution of variables is delayed until request time and occurs before parsing.
109    *       <br>This allows you to, for example, pull in a JSON construct from a properties file based on the locale of the HTTP request.
110    * </ul>
111    *
112    * @return The annotation value.
113    */
114   String[] examples() default {};
115
116   /**
117    * <mk>headers</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#responseObject">Swagger Response Object</a>.
118    *
119    * <h5 class='section'>Used for:</h5>
120    * <ul class='spaced-list'>
121    *    <li>
122    *       Server-side generated Swagger documentation.
123    * </ul>
124    *
125    * @return The annotation value.
126    */
127   Header[] headers() default {};
128
129   /**
130    * <mk>schema</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#responseObject">Swagger Response Object</a>.
131    *
132    * <h5 class='section'>Used for:</h5>
133    * <ul class='spaced-list'>
134    *    <li>
135    *       Server-side schema-based serializing and serializing validation.
136    *    <li>
137    *       Server-side generated Swagger documentation.
138    * </ul>
139    *
140    * @return The annotation value.
141    */
142   Schema schema() default @Schema;
143
144}