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.media;
18
19 import io.swagger.v3.oas.annotations.extensions.Extension;
20
21 import java.lang.annotation.ElementType;
22 import java.lang.annotation.Inherited;
23 import java.lang.annotation.Retention;
24 import java.lang.annotation.RetentionPolicy;
25 import java.lang.annotation.Target;
26
27 /**
28  * The annotation may be used to define the content/media type  of a parameter, request or response, by defining it as
29  * field {@link io.swagger.v3.oas.annotations.Parameter#content()}, {@link io.swagger.v3.oas.annotations.parameters.RequestBody#content()} or {@link io.swagger.v3.oas.annotations.responses.ApiResponse#content()}.
30  * <p>If {@link Content#schema()} is defined, swagger-jaxrs2 reader engine will consider it along with
31  * JAX-RS annotations, element type and context as input to resolve the annotated element into an OpenAPI schema
32  * definition for such element.</p>
33  *
34  * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#exampleObject">Example (OpenAPI specification)</a>
35  * @see Schema
36  * @see io.swagger.v3.oas.annotations.Parameter
37  * @see io.swagger.v3.oas.annotations.responses.ApiResponse
38  * @see io.swagger.v3.oas.annotations.parameters.RequestBody
39  **/
40 @Target({ElementType.ANNOTATION_TYPE})
41 @Retention(RetentionPolicy.RUNTIME)
42 @Inherited
43 public @interface Content {
44     /**
45      * The media type that this object applies to.
46      *
47      * @return the media type value
48      **/
49     String mediaType() default "";
50
51     /**
52      * An array of examples used to show the use of the associated schema.
53      *
54      * @return the list of examples
55      **/
56     ExampleObject[] examples() default {};
57
58     /**
59      * The schema defining the type used for the content.
60      *
61      * @return the schema of this media type
62      **/
63     Schema schema() default @Schema();
64
65     /**
66      * The schema of the array that defines the type used for the content.
67      *
68      * @return the schema of the array
69      */
70     ArraySchema array() default @ArraySchema();
71
72     /**
73      * An array of encodings
74      * The key, being the property name, MUST exist in the schema as a property.
75      *
76      * @return the array of encodings
77      */
78     Encoding[] encoding() default {};
79
80     /**
81      * The list of optional extensions
82      *
83      * @return an optional array of extensions
84      */
85     Extension[] extensions() default {};
86
87 }
88