1 package io.swagger.v3.oas.annotations.responses;
2
3 import io.swagger.v3.oas.annotations.extensions.Extension;
4 import io.swagger.v3.oas.annotations.headers.Header;
5 import io.swagger.v3.oas.annotations.links.Link;
6 import io.swagger.v3.oas.annotations.media.Content;
7
8 import java.lang.annotation.Inherited;
9 import java.lang.annotation.Repeatable;
10 import java.lang.annotation.Retention;
11 import java.lang.annotation.RetentionPolicy;
12 import java.lang.annotation.Target;
13
14 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
15 import static java.lang.annotation.ElementType.METHOD;
16 import static java.lang.annotation.ElementType.TYPE;
17
18 /**
19 * The annotation may be used at method level or as field of {@link io.swagger.v3.oas.annotations.Operation} to define one or more responses of the
20 * Operation.
21 *
22 * <p>swagger-jaxrs2 reader engine considers this annotation along with method return type and context as input to
23 * resolve the OpenAPI Operation responses.</p>
24 *
25 * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#responseObject">Response (OpenAPI specification)</a>
26 * @see io.swagger.v3.oas.annotations.Operation
27 **/
28 @Target({METHOD, TYPE, ANNOTATION_TYPE})
29 @Retention(RetentionPolicy.RUNTIME)
30 @Inherited
31 @Repeatable(ApiResponses.class)
32 public @interface ApiResponse {
33 /**
34 * A short description of the response.
35 *
36 * @return description of the response
37 **/
38 String description() default "";
39
40 /**
41 * The HTTP response code, or 'default', for the supplied response. May only have 1 default entry.
42 *
43 * @return response code
44 **/
45 String responseCode() default "default";
46
47 /**
48 * An array of response headers. Allows additional information to be included with response.
49 *
50 * @return array of headers
51 **/
52 Header[] headers() default {};
53
54 /**
55 * An array of operation links that can be followed from the response.
56 *
57 * @return array of links
58 **/
59 Link[] links() default {};
60
61 /**
62 * An array containing descriptions of potential response payloads, for different media types.
63 *
64 * @return array of content
65 **/
66 Content[] content() default {};
67
68 /**
69 * The list of optional extensions
70 *
71 * @return an optional array of extensions
72 */
73 Extension[] extensions() default {};
74
75 /**
76 * A reference to a response defined in components responses.
77 *
78 * @since 2.0.3
79 * @return the reference
80 **/
81 String ref() default "";
82
83 /**
84 * Set to true to resolve the response schema from method return type
85 *
86 * @since 2.2.0
87 **/
88 boolean useReturnTypeSchema() default false;
89
90 }
91