1 /**
2 * Copyright 2017 SmartBear Software
3 * <p>
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 * <p>
8 * http://www.apache.org/licenses/LICENSE-2.0
9 * <p>
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package io.swagger.v3.oas.annotations.responses;
18
19 import io.swagger.v3.oas.annotations.extensions.Extension;
20 import io.swagger.v3.oas.annotations.headers.Header;
21 import io.swagger.v3.oas.annotations.links.Link;
22 import io.swagger.v3.oas.annotations.media.Content;
23
24 import java.lang.annotation.Inherited;
25 import java.lang.annotation.Repeatable;
26 import java.lang.annotation.Retention;
27 import java.lang.annotation.RetentionPolicy;
28 import java.lang.annotation.Target;
29
30 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
31 import static java.lang.annotation.ElementType.METHOD;
32 import static java.lang.annotation.ElementType.TYPE;
33
34 /**
35 * 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
36 * Operation.
37 *
38 * <p>swagger-jaxrs2 reader engine considers this annotation along with method return type and context as input to
39 * resolve the OpenAPI Operation responses.</p>
40 *
41 * @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>
42 * @see io.swagger.v3.oas.annotations.Operation
43 **/
44 @Target({METHOD, TYPE, ANNOTATION_TYPE})
45 @Retention(RetentionPolicy.RUNTIME)
46 @Inherited
47 @Repeatable(ApiResponses.class)
48 public @interface ApiResponse {
49 /**
50 * A short description of the response.
51 *
52 * @return description of the response
53 **/
54 String description() default "";
55
56 /**
57 * The HTTP response code, or 'default', for the supplied response. May only have 1 default entry.
58 *
59 * @return response code
60 **/
61 String responseCode() default "default";
62
63 /**
64 * An array of response headers. Allows additional information to be included with response.
65 *
66 * @return array of headers
67 **/
68 Header[] headers() default {};
69
70 /**
71 * An array of operation links that can be followed from the response.
72 *
73 * @return array of links
74 **/
75 Link[] links() default {};
76
77 /**
78 * An array containing descriptions of potential response payloads, for different media types.
79 *
80 * @return array of content
81 **/
82 Content[] content() default {};
83
84 /**
85 * The list of optional extensions
86 *
87 * @return an optional array of extensions
88 */
89 Extension[] extensions() default {};
90
91 /**
92 * A reference to a response defined in components responses.
93 *
94 * @since 2.0.3
95 * @return the reference
96 **/
97 String ref() default "";
98
99 }
100