modules/swagger-annotations/src/main/java/io/swagger/annotations/ApiKeyAuthDefinition.java

@@ -0,0 +1,61 @@
+package io.swagger.annotations;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Annotation used to construct ApiKey Auth security definition.
+ */
+public @interface ApiKeyAuthDefinition {
+
+    /**
+     * Key used to refer to this security definition
+     *
+     * @return key used to refer to this security definition
+     */
+    String key();
+
+    /**
+     * A short description for security scheme.
+     * @return a short description for security scheme.
+     */
+    String description() default "";
+
+    /**
+     * The location of the API key. Valid values are "query" or "header"
+     *
+     * @return
+     */
+    ApiKeyLocation in();
+
+    /**
+     * The name of the header or query parameter to be used.
+     * @return the name of the header or query parameter to be used.
+     */
+    String name();
+
+    enum ApiKeyLocation{
+        HEADER, QUERY;
+
+        private static Map<String, ApiKeyLocation> names = new HashMap<String, ApiKeyLocation>();
+
+        public static ApiKeyLocation forValue(String value) {
+            return names.get(value.toLowerCase());
+        }
+
+        public String toValue() {
+            for (Map.Entry<String, ApiKeyLocation> entry : names.entrySet()) {
+                if (entry.getValue() == this) {
+                    return entry.getKey();
+                }
+            }
+
+            return null; // or fail
+        }
+
+        static {
+            names.put("header", HEADER);
+            names.put("query", QUERY);
+        }
+    }
+}

modules/swagger-annotations/src/main/java/io/swagger/annotations/BasicAuthDefinition.java

@@ -0,0 +1,21 @@
+package io.swagger.annotations;
+
+/**
+ * Annotation used to construct OAuth security definition.
+ */
+public @interface BasicAuthDefinition {
+
+    /**
+     * Key used to refer to this security definition
+     *
+     * @return key used to refer to this security definition
+     */
+    String key();
+
+    /**
+     * A short description for security scheme.
+     *
+     * @return a short description for security scheme.
+     */
+    String description() default "";
+}

modules/swagger-annotations/src/main/java/io/swagger/annotations/OAuth2Definition.java

@@ -0,0 +1,51 @@
+package io.swagger.annotations;
+
+/**
+ * Annotation used to construct OAuth security definition.
+ */
+public @interface OAuth2Definition {
+
+    /**
+     * Key used to refer to this security definition
+     *
+     * @return key used to refer to this security definition
+     */
+    String key();
+
+    /**
+     * A short description for security scheme.
+     *
+     * @return a short description for security scheme.
+     */
+    String description() default "";
+
+    /**
+     * The flow used by the OAuth2 security scheme.
+     * Valid values are "implicit", "password", "application" or "accessCode".
+     *
+     * @return
+     */
+    Flow flow();
+
+    /**
+     * The authorization URL to be used for this flow. This SHOULD be in the form of a URL.
+     * Required for implicit and access code flows
+     *
+     * @return the authorization URL to be used for this flow. This SHOULD be in the form of a URL.
+     */
+    String authorizationUrl() default "";
+
+    /**
+     * The token URL to be used for this flow. This SHOULD be in the form of a URL.
+     * Required for password, applcation, and access code flows.
+     *
+     * @return the token URL to be used for this flow. This SHOULD be in the form of a URL.
+     */
+    String tokenUrl() default "";
+
+    Scope[] scopes() default {};
+
+    enum Flow {
+        IMPLICIT, ACCESS_CODE, PASSWORD, APPLICATION
+    }
+}

modules/swagger-annotations/src/main/java/io/swagger/annotations/Scope.java

@@ -0,0 +1,21 @@
+package io.swagger.annotations;
+
+/**
+ * The available scopes for an OAuth2 security scheme
+ */
+public @interface Scope {
+
+    /**
+     * The name of the scope
+     *
+     * @return the name of the scope
+     */
+    String name();
+
+    /**
+     * A short description of the scope
+     *
+     * @return a short description of the scope
+     */
+    String description();
+}

modules/swagger-annotations/src/main/java/io/swagger/annotations/SecurityDefinition.java

@@ -0,0 +1,35 @@
+package io.swagger.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * An aggregation of all security definitions.
+ */
+@Target (ElementType.ANNOTATION_TYPE)
+@Retention (RetentionPolicy.RUNTIME)
+public @interface SecurityDefinition {
+
+    /**
+     * OAuth security defintion objects
+     *
+     * @return OAuth security defintion objects
+     */
+    OAuth2Definition[] oAuth2Definitions() default {};
+
+    /**
+     * API Key security defintion objects
+     *
+     * @return API Key security defintion objects
+     */
+    ApiKeyAuthDefinition[] apiKeyAuthDefintions() default {};
+
+    /**
+     * Basic auth security definition objects
+     *
+     * @return basic auth security definition objects
+     */
+    BasicAuthDefinition[] basicAuthDefinions() default {};
+}

modules/swagger-annotations/src/main/java/io/swagger/annotations/SwaggerDefinition.java

@@ -24,7 +24,6 @@
 
 /**
  * Annotation that configures definition level metadata. Still missing are the following:
- * - Security Definitions
  * - Security Requirements
  * - Parameters
  * - Responses
@@ -88,7 +87,13 @@
      */
     Tag[] tags() default @Tag(name = "");
 
-    ;
+
+    /**
+     * Defintions for security schemes
+     *
+     * @return defintions for security schemes
+     */
+    SecurityDefinition securityDefinition() default @SecurityDefinition();
 
     /**
      * General metadata for this Swagger definition.

modules/swagger-jaxrs/src/main/java/io/swagger/jaxrs/Reader.java

@@ -21,13 +21,17 @@
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiImplicitParam;
 import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiKeyAuthDefinition;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiResponse;
 import io.swagger.annotations.ApiResponses;
 import io.swagger.annotations.Authorization;
 import io.swagger.annotations.AuthorizationScope;
+import io.swagger.annotations.BasicAuthDefinition;
 import io.swagger.annotations.Info;
+import io.swagger.annotations.OAuth2Definition;
 import io.swagger.annotations.ResponseHeader;
+import io.swagger.annotations.Scope;
 import io.swagger.annotations.SwaggerDefinition;
 import io.swagger.converter.ModelConverters;
 import io.swagger.jaxrs.config.DefaultReaderConfig;
@@ -47,6 +51,7 @@
 import io.swagger.models.SecurityRequirement;
 import io.swagger.models.Swagger;
 import io.swagger.models.Tag;
+import io.swagger.models.auth.In;
 import io.swagger.models.parameters.FormParameter;
 import io.swagger.models.parameters.HeaderParameter;
 import io.swagger.models.parameters.Parameter;
@@ -458,6 +463,46 @@ protected void readSwaggerConfig(Class<?> cls, SwaggerDefinition config) {
             }
         }
 
+        for (OAuth2Definition oAuth2Config : config.securityDefinition().oAuth2Definitions()) {
+            io.swagger.models.auth.OAuth2Definition oAuth2Definition = new io.swagger.models.auth.OAuth2Definition();
+            OAuth2Definition.Flow flow = oAuth2Config.flow();
+
+            if (flow.equals(OAuth2Definition.Flow.ACCESS_CODE)) {
+                oAuth2Definition = oAuth2Definition.accessCode(oAuth2Config.authorizationUrl(), oAuth2Config.tokenUrl());
+            } else if (flow.equals(OAuth2Definition.Flow.APPLICATION)) {
+                oAuth2Definition = oAuth2Definition.application(oAuth2Config.tokenUrl());
+            } else if (flow.equals(OAuth2Definition.Flow.IMPLICIT)) {
+                oAuth2Definition = oAuth2Definition.implicit(oAuth2Config.authorizationUrl());
+            } else {
+                oAuth2Definition = oAuth2Definition.password(oAuth2Config.tokenUrl());
+            }
+
+            for (Scope scope : oAuth2Config.scopes()) {
+                oAuth2Definition.addScope(scope.name(), scope.description());
+            }
+
+            oAuth2Definition.setDescription(oAuth2Config.description());
+            swagger.addSecurityDefinition(oAuth2Config.key(), oAuth2Definition);
+        }
+
+        for (ApiKeyAuthDefinition apiKeyAuthConfig : config.securityDefinition().apiKeyAuthDefintions()) {
+            io.swagger.models.auth.ApiKeyAuthDefinition apiKeyAuthDefinition = new io.swagger.models.auth.ApiKeyAuthDefinition();
+
+            apiKeyAuthDefinition.setName(apiKeyAuthConfig.name());
+            apiKeyAuthDefinition.setIn(In.valueOf(apiKeyAuthConfig.in().toValue()));
+            apiKeyAuthDefinition.setDescription(apiKeyAuthConfig.description());
+
+            swagger.addSecurityDefinition(apiKeyAuthConfig.key(), apiKeyAuthDefinition);
+        }
+
+        for (BasicAuthDefinition basicAuthConfig : config.securityDefinition().basicAuthDefinions()) {
+            io.swagger.models.auth.BasicAuthDefinition basicAuthDefinition = new io.swagger.models.auth.BasicAuthDefinition();
+
+            basicAuthDefinition.setDescription(basicAuthConfig.description());
+
+            swagger.addSecurityDefinition(basicAuthConfig.key(), basicAuthDefinition);
+        }
+
         if (!config.externalDocs().value().isEmpty()) {
             ExternalDocs externalDocs = swagger.getExternalDocs();
             if (externalDocs == null) {

modules/swagger-servlet/src/main/java/io/swagger/servlet/Reader.java

@@ -1,6 +1,10 @@
 package io.swagger.servlet;
 
+import io.swagger.annotations.ApiKeyAuthDefinition;
+import io.swagger.annotations.BasicAuthDefinition;
 import io.swagger.annotations.Info;
+import io.swagger.annotations.OAuth2Definition;
+import io.swagger.annotations.Scope;
 import io.swagger.annotations.SwaggerDefinition;
 import io.swagger.models.Contact;
 import io.swagger.models.ExternalDocs;
@@ -11,6 +15,7 @@
 import io.swagger.models.Scheme;
 import io.swagger.models.Swagger;
 import io.swagger.models.Tag;
+import io.swagger.models.auth.In;
 import io.swagger.models.parameters.Parameter;
 import io.swagger.servlet.extensions.ReaderExtension;
 import io.swagger.servlet.extensions.ReaderExtensions;
@@ -154,6 +159,45 @@ private void readSwaggerConfig(SwaggerDefinition config) {
                 externalDocs.setUrl(config.externalDocs().url());
             }
         }
+        for (OAuth2Definition oAuth2Config : config.securityDefinition().oAuth2Definitions()) {
+            io.swagger.models.auth.OAuth2Definition oAuth2Definition = new io.swagger.models.auth.OAuth2Definition();
+            OAuth2Definition.Flow flow = oAuth2Config.flow();
+
+            if (flow.equals(OAuth2Definition.Flow.ACCESS_CODE)) {
+                oAuth2Definition = oAuth2Definition.accessCode(oAuth2Config.authorizationUrl(), oAuth2Config.tokenUrl());
+            } else if (flow.equals(OAuth2Definition.Flow.APPLICATION)) {
+                oAuth2Definition = oAuth2Definition.application(oAuth2Config.tokenUrl());
+            } else if (flow.equals(OAuth2Definition.Flow.IMPLICIT)) {
+                oAuth2Definition = oAuth2Definition.implicit(oAuth2Config.authorizationUrl());
+            } else {
+                oAuth2Definition = oAuth2Definition.password(oAuth2Config.tokenUrl());
+            }
+
+            for (Scope scope : oAuth2Config.scopes()) {
+                oAuth2Definition.addScope(scope.name(), scope.description());
+            }
+
+            oAuth2Definition.setDescription(oAuth2Config.description());
+            swagger.addSecurityDefinition(oAuth2Config.key(), oAuth2Definition);
+        }
+
+        for (ApiKeyAuthDefinition apiKeyAuthConfig : config.securityDefinition().apiKeyAuthDefintions()) {
+            io.swagger.models.auth.ApiKeyAuthDefinition apiKeyAuthDefinition = new io.swagger.models.auth.ApiKeyAuthDefinition();
+
+            apiKeyAuthDefinition.setName(apiKeyAuthConfig.name());
+            apiKeyAuthDefinition.setIn(In.forValue(apiKeyAuthConfig.in().toValue()));
+            apiKeyAuthDefinition.setDescription(apiKeyAuthConfig.description());
+
+            swagger.addSecurityDefinition(apiKeyAuthConfig.key(), apiKeyAuthDefinition);
+        }
+
+        for (BasicAuthDefinition basicAuthConfig : config.securityDefinition().basicAuthDefinions()) {
+            io.swagger.models.auth.BasicAuthDefinition basicAuthDefinition = new io.swagger.models.auth.BasicAuthDefinition();
+
+            basicAuthDefinition.setDescription(basicAuthConfig.description());
+
+            swagger.addSecurityDefinition(basicAuthConfig.key(), basicAuthDefinition);
+        }
 
         for (io.swagger.annotations.Tag tagConfig : config.tags()) {
             if (StringUtils.isNotBlank(tagConfig.name())) {

modules/swagger-servlet/src/test/java/io/swagger/servlet/resources/ResourceWithAnnotations.java

@@ -3,18 +3,22 @@
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiImplicitParam;
 import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiKeyAuthDefinition;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiResponse;
 import io.swagger.annotations.ApiResponses;
 import io.swagger.annotations.Authorization;
 import io.swagger.annotations.AuthorizationScope;
+import io.swagger.annotations.BasicAuthDefinition;
 import io.swagger.annotations.Contact;
 import io.swagger.annotations.Extension;
 import io.swagger.annotations.ExtensionProperty;
 import io.swagger.annotations.ExternalDocs;
 import io.swagger.annotations.Info;
 import io.swagger.annotations.License;
+import io.swagger.annotations.OAuth2Definition;
 import io.swagger.annotations.ResponseHeader;
+import io.swagger.annotations.SecurityDefinition;
 import io.swagger.annotations.SwaggerDefinition;
 import io.swagger.annotations.Tag;
 import io.swagger.servlet.models.SampleData;
@@ -44,6 +48,16 @@
         consumes = {"application/json", "application/xml", ""},
         produces = {"application/json", "application/xml", ""},
         schemes = {SwaggerDefinition.Scheme.HTTP, SwaggerDefinition.Scheme.HTTPS, SwaggerDefinition.Scheme.DEFAULT},
+        securityDefinition = @SecurityDefinition(
+                basicAuthDefinions = {
+                        @BasicAuthDefinition(key = "basicAuth")},
+                apiKeyAuthDefintions = {
+                        @ApiKeyAuthDefinition(key = "apiKeyAuth", name = "apiKey", in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER)},
+                oAuth2Definitions = {
+                        @OAuth2Definition(key = "oAuth2AccessCode", flow = OAuth2Definition.Flow.ACCESS_CODE),
+                        @OAuth2Definition(key = "oAuth2Password", flow = OAuth2Definition.Flow.PASSWORD)
+                }
+        ),
         tags = {
                 @Tag(name = "tests", description = "tests"),
                 @Tag(name = "tests", description = "tests",