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.servers;
18
19 import io.swagger.v3.oas.annotations.extensions.Extension;
20
21 import java.lang.annotation.Inherited;
22 import java.lang.annotation.Repeatable;
23 import java.lang.annotation.Retention;
24 import java.lang.annotation.RetentionPolicy;
25 import java.lang.annotation.Target;
26
27 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
28 import static java.lang.annotation.ElementType.TYPE;
29 import static java.lang.annotation.ElementType.METHOD;
30
31 /**
32  * The annotation may be applied at class or method level, or in {@link io.swagger.v3.oas.annotations.Operation#servers()} to define servers for the
33  * single operation (when applied at method level) or for all operations of a class (when applied at class level).
34  * <p>It can also be used in {@link io.swagger.v3.oas.annotations.OpenAPIDefinition#servers()} to define spec level servers.</p>
35  *
36  * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#serverObject">Server (OpenAPI specification)</a>
37  * @see io.swagger.v3.oas.annotations.OpenAPIDefinition
38  * @see io.swagger.v3.oas.annotations.Operation
39  **/
40 @Target({METHOD, TYPE, ANNOTATION_TYPE})
41 @Retention(RetentionPolicy.RUNTIME)
42 @Repeatable(Servers.class)
43 @Inherited
44 public @interface Server {
45     /**
46      * Required. A URL to the target host.
47      * This URL supports Server Variables and may be relative, to indicate that the host location is relative to the location where the
48      * OpenAPI definition is being served. Variable substitutions will be made when a variable is named in {brackets}.
49      *
50      * @return String url
51      **/
52     String url() default "";
53
54     /**
55      * An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
56      *
57      * @return String description
58      **/
59     String description() default "";
60
61     /**
62      * An array of variables used for substitution in the server's URL template.
63      *
64      * @return array of ServerVariables
65      **/
66     ServerVariable[] variables() default {};
67
68     /**
69      * The list of optional extensions
70      *
71      * @return an optional array of extensions
72      */
73     Extension[] extensions() default {};
74
75 }
76