1 package io.swagger.v3.oas.annotations.media;
2
3 import io.swagger.v3.oas.annotations.OpenAPI31;
4 import io.swagger.v3.oas.annotations.extensions.Extension;
5
6 import java.lang.annotation.ElementType;
7 import java.lang.annotation.Inherited;
8 import java.lang.annotation.Retention;
9 import java.lang.annotation.RetentionPolicy;
10 import java.lang.annotation.Target;
11
12 /**
13 * The annotation may be used to define the content/media type of a parameter, request or response, by defining it as
14 * 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()}.
15 * <p>If {@link Content#schema()} is defined, swagger-jaxrs2 reader engine will consider it along with
16 * JAX-RS annotations, element type and context as input to resolve the annotated element into an OpenAPI schema
17 * definition for such element.</p>
18 *
19 * @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>
20 * @see Schema
21 * @see io.swagger.v3.oas.annotations.Parameter
22 * @see io.swagger.v3.oas.annotations.responses.ApiResponse
23 * @see io.swagger.v3.oas.annotations.parameters.RequestBody
24 **/
25 @Target({ElementType.ANNOTATION_TYPE})
26 @Retention(RetentionPolicy.RUNTIME)
27 @Inherited
28 public @interface Content {
29 /**
30 * The media type that this object applies to.
31 *
32 * @return the media type value
33 **/
34 String mediaType() default "";
35
36 /**
37 * An array of examples used to show the use of the associated schema.
38 *
39 * @return the list of examples
40 **/
41 ExampleObject[] examples() default {};
42
43 /**
44 * The schema defining the type used for the content.
45 *
46 * @return the schema of this media type
47 **/
48 Schema schema() default @Schema();
49
50 /**
51 * The schema properties defined for schema provided in @Schema
52 *
53 * @since 2.2.0
54 * @return the schema properties
55 */
56 SchemaProperty[] schemaProperties() default {};
57
58 /**
59 * The additionalProperties schema defined for schema provided in @Schema
60 * If the additionalProperties schema is an array, use additionalPropertiesArraySchema
61 *
62 * @since 2.2.0
63 * @return the additionalProperties schema
64 */
65 Schema additionalPropertiesSchema() default @Schema();
66
67 /**
68 * The additionalProperties array schema defined for schema provided in @Schema
69 * If the additionalProperties schema is not an array, use additionalPropertiesSchema
70 *
71 * @since 2.2.16
72 * @return the additionalProperties array schema
73 */
74 ArraySchema additionalPropertiesArraySchema() default @ArraySchema();
75
76 /**
77 * The schema of the array that defines the type used for the content.
78 *
79 * @return the schema of the array
80 */
81 ArraySchema array() default @ArraySchema();
82
83 /**
84 * An array of encodings
85 * The key, being the property name, MUST exist in the schema as a property.
86 *
87 * @return the array of encodings
88 */
89 Encoding[] encoding() default {};
90
91 /**
92 * The list of optional extensions
93 *
94 * @return an optional array of extensions
95 */
96 Extension[] extensions() default {};
97
98 /**
99 * Subschemas to be applied for a given condition.
100 *
101 * @since 2.2.12 / OpenAPI 3.1
102 * @return list of dependent schemas.
103 */
104 @OpenAPI31
105 DependentSchema[] dependentSchemas() default {};
106
107 /**
108 * Provides the content schema related to this schema
109 *
110 * @since 2.2.12 / OpenAPI 3.1
111 * @return content schema
112 */
113 @OpenAPI31
114 Schema contentSchema() default @Schema();
115
116 /**
117 * Provides property names related to this schema
118 *
119 * @since 2.2.12 / OpenAPI 3.1
120 * @return proeprty names
121 */
122 @OpenAPI31
123 Schema propertyNames() default @Schema();
124
125 /**
126 * Provides the if sub schema related to this schema
127 *
128 * @since 2.2.12 / OpenAPI 3.1
129 * @return if schema
130 */
131 @OpenAPI31
132 Schema _if() default @Schema();
133
134 /**
135 * Provides the then sub schema related to this schema
136 *
137 * @since 2.2.12 / OpenAPI 3.1
138 * @return then schema
139 */
140 @OpenAPI31
141 Schema _then() default @Schema();
142
143 /**
144 * Provides the else sub schema related to this schema
145 *
146 * @since 2.2.12 / OpenAPI 3.1
147 * @return else schema
148 */
149 @OpenAPI31
150 Schema _else() default @Schema();
151
152 /**
153 * Set schemas to validate according a given condition.
154 *
155 * @since 2.2.12 / OpenAPI 3.1
156 * @return not schema to be validated
157 **/
158 Schema not() default @Schema();
159
160 /**
161 * Provides the oneOf sub schemas related to this schema.
162 *
163 * @since 2.2.12 / OpenAPI 3.1
164 * @return oneOf sub schemas
165 **/
166 Schema[] oneOf() default {};
167
168 /**
169 * Provides the anyOf sub schemas related to this schema.
170 *
171 * @since 2.2.12 / OpenAPI 3.1
172 * @return anyOf sub schemas
173 **/
174 Schema[] anyOf() default {};
175
176 /**
177 * Provides the allOf sub schemas related to this schema..
178 *
179 * @since 2.2.12 / OpenAPI 3.1
180 * @return allOf sub schemas
181 **/
182 Schema[] allOf() default {};
183
184 }
185