1 package io.swagger.v3.oas.annotations.media;
2
3 import io.swagger.v3.oas.annotations.extensions.Extension;
4
5 import java.lang.annotation.ElementType;
6 import java.lang.annotation.Inherited;
7 import java.lang.annotation.Retention;
8 import java.lang.annotation.RetentionPolicy;
9 import java.lang.annotation.Target;
10
11 /**
12  * The annotation may be used to add one or more examples to the definition of a parameter, request or response content,
13  * by defining it as field {@link io.swagger.v3.oas.annotations.Parameter#examples()} or {@link Content#examples()}
14  *
15  * @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>
16  **/
17 @Target({ElementType.ANNOTATION_TYPE})
18 @Retention(RetentionPolicy.RUNTIME)
19 @Inherited
20 public @interface ExampleObject {
21     /**
22      * A unique name to identify this particular example
23      *
24      * @return the name of the example
25      **/
26     String name() default "";
27
28     /**
29      * A brief summary of the purpose or context of the example
30      *
31      * @return a summary of the example
32      **/
33     String summary() default "";
34
35     /**
36      * A string representation of the example.  This is mutually exclusive with the externalValue property, and ignored if the externalValue property is specified.  If the media type associated with the example allows parsing into an object, it may be converted from a string
37      *
38      * @return the value of the example
39      **/
40     String value() default "";
41
42     /**
43      * A URL to point to an external document to be used as an example.  This is mutually exclusive with the value property.
44      *
45      * @return an external URL of the example
46      **/
47     String externalValue() default "";
48
49     /**
50      * The list of optional extensions
51      *
52      * @return an optional array of extensions
53      */
54     Extension[] extensions() default {};
55
56     /**
57      * A reference to a example defined in components examples.
58      *
59      * @since 2.0.3
60      * @return the reference
61      **/
62     String ref() default "";
63
64     /**
65      * A description of the purpose or context of the example
66      *
67      * @since 2.1.0
68      * @return a description of the example
69      **/
70     String description() default "";
71
72 }
73