1 package io.swagger.v3.oas.annotations.links;
2
3 import io.swagger.v3.oas.annotations.extensions.Extension;
4 import io.swagger.v3.oas.annotations.servers.Server;
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 applied in {@link io.swagger.v3.oas.annotations.responses.ApiResponse#links()} to add OpenAPI links to a response.
14 *
15 * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#linkObject">Link (OpenAPI specification)</a>
16 * @see io.swagger.v3.oas.annotations.responses.ApiResponse
17 **/
18 @Target({ElementType.ANNOTATION_TYPE})
19 @Retention(RetentionPolicy.RUNTIME)
20 @Inherited
21 public @interface Link {
22 /**
23 * The name of this link.
24 *
25 * @return the link's name
26 **/
27 String name() default "";
28
29 /**
30 * A relative or absolute reference to an OAS operation. This field is mutually exclusive of the operationId field, and must point to an Operation Object. Relative operationRef values may be used to locate an existing Operation Object in the OpenAPI definition. Ignored if the operationId property is specified.
31 *
32 * @return an operation reference
33 **/
34 String operationRef() default "";
35
36 /**
37 * The name of an existing, resolvable OAS operation, as defined with a unique operationId. This field is mutually exclusive of the operationRef field.
38 *
39 * @return an operation ID
40 **/
41 String operationId() default "";
42
43 /**
44 * Array of parameters to pass to an operation as specified with operationId or identified via operationRef.
45 *
46 * @return the list of parameters for this link
47 **/
48 LinkParameter[] parameters() default {};
49
50 /**
51 * A description of the link. CommonMark syntax may be used for rich text representation.
52 *
53 * @return the link's description
54 **/
55 String description() default "";
56
57 /**
58 * A literal value or {expression} to use as a request body when calling the target operation.
59 *
60 * @return the request body of this link
61 **/
62 String requestBody() default "";
63
64 /**
65 * An alternative server to service this operation.
66 *
67 * @return the server associated to this link
68 **/
69 Server server() default @Server;
70
71 /**
72 * The list of optional extensions
73 *
74 * @return an optional array of extensions
75 */
76 Extension[] extensions() default {};
77
78 /**
79 * A reference to a link defined in components links.
80 *
81 * @since 2.0.3
82 * @return the reference
83 **/
84 String ref() default "";
85
86 }
87