Added scheme property to HttpApiKeyAuth trait

docs/source/1.0/spec/core/auth-traits.rst

@@ -216,6 +216,9 @@ properties:
       - ``string``
       - **Required**. Defines the location of where the key is serialized.
         This value can be set to ``header`` or ``query``.
+    * - scheme
+      - ``string``
+      - Defines the ApiKey scheme to set on the intended Authoriation header
 
 The following example defines a service that accepts an API key in the "X-Api-Key"
 HTTP header:
@@ -228,6 +231,14 @@ HTTP header:
     }
 
 
+.. code-block:: smithy
+
+    @httpApiKeyAuth(scheme: "ApiKey", name: "Authorization", in: "header")
+    service WeatherService {
+        version: "2017-02-11",
+    }
+
+
 .. smithy-trait:: smithy.api#optionalAuth
 .. _optionalAuth-trait:
 

smithy-linters/src/test/resources/software/amazon/smithy/linters/errorfiles/http-api-key-scheme-trait-validator-test.errors

@@ -0,0 +1 @@
+[ERROR] ns.foo#MyService: httpApiKeyAuth trait must use in="header" when scheme is specified. | HttpApiKeyAuthTrait

smithy-linters/src/test/resources/software/amazon/smithy/linters/errorfiles/http-api-key-scheme-trait-validator-test.json

@@ -0,0 +1,39 @@
+{
+    "smithy": "1.0",
+    "shapes": {
+        "ns.foo#MyService": {
+            "type": "service",
+            "version": "2017-01-17",
+            "operations": [
+                {
+                    "target": "ns.foo#A"
+                }
+            ],
+            "traits": {
+                "smithy.api#httpApiKeyAuth": {
+                    "scheme": "Baz",
+                    "name": "ApiKeyName",
+                    "in": "query"
+                }
+            }
+        },
+        "ns.foo#A": {
+            "type": "operation",
+            "input": {
+                "target": "ns.foo#AInput"
+            },
+            "output": {
+                "target": "ns.foo#AOutput"
+            },
+            "traits": {
+                "smithy.api#readonly": { }
+            }
+        },
+        "ns.foo#AInput": {
+            "type": "structure"
+        },
+        "ns.foo#AOutput": {
+            "type": "structure"
+        }
+    }
+}

smithy-model/src/main/java/software/amazon/smithy/model/traits/HttpApiKeyAuthTrait.java

@@ -15,6 +15,7 @@
 
 package software.amazon.smithy.model.traits;
 
+import java.util.Optional;
 import software.amazon.smithy.model.node.Node;
 import software.amazon.smithy.model.node.ObjectNode;
 import software.amazon.smithy.model.shapes.ShapeId;
@@ -29,15 +30,21 @@ public final class HttpApiKeyAuthTrait extends AbstractTrait implements ToSmithy
 
     public static final ShapeId ID = ShapeId.from("smithy.api#httpApiKeyAuth");
 
+    private final String scheme;
     private final String name;
     private final Location in;
 
     private HttpApiKeyAuthTrait(Builder builder) {
         super(ID, builder.getSourceLocation());
+        scheme = builder.scheme;
         name = SmithyBuilder.requiredState("name", builder.name);
         in = SmithyBuilder.requiredState("in", builder.in);
     }
 
+    public Optional<String> getScheme() {
+        return Optional.ofNullable(scheme);
+    }
+
     public String getName() {
         return name;
     }
@@ -50,17 +57,21 @@ public Location getIn() {
     public Builder toBuilder() {
         return builder()
                 .sourceLocation(getSourceLocation())
+                .scheme(getScheme().orElse(null))
                 .name(getName())
                 .in(getIn());
     }
 
     @Override
     protected Node createNode() {
-        return Node.objectNodeBuilder()
+        ObjectNode.Builder builder = Node.objectNodeBuilder()
                 .sourceLocation(getSourceLocation())
                 .withMember("name", getName())
-                .withMember("in", getIn().toString())
-                .build();
+                .withMember("in", getIn().toString());
+        getScheme().ifPresent(scheme -> {
+            builder.withMember("scheme", getScheme().get());
+        });
+        return builder.build();
     }
 
     public static Builder builder() {
@@ -101,13 +112,15 @@ public Provider() {
         public Trait createTrait(ShapeId target, Node value) {
             ObjectNode objectNode = value.expectObjectNode();
             Builder builder = builder().sourceLocation(value.getSourceLocation());
+            builder.scheme(objectNode.getStringMemberOrDefault("scheme", null));
             builder.name(objectNode.expectStringMember("name").getValue());
             builder.in(Location.from(objectNode.expectStringMember("in").expectOneOf("header", "query")));
             return builder.build();
         }
     }
 
     public static final class Builder extends AbstractTraitBuilder<HttpApiKeyAuthTrait, Builder> {
+        private String scheme;
         private String name;
         private Location in;
 
@@ -118,6 +131,11 @@ public HttpApiKeyAuthTrait build() {
             return new HttpApiKeyAuthTrait(this);
         }
 
+        public Builder scheme(String scheme) {
+            this.scheme = scheme;
+            return this;
+        }
+
         public Builder name(String name) {
             this.name = name;
             return this;

smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/HttpApiKeyAuthTraitValidator.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.smithy.model.validation.validators;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.shapes.ServiceShape;
+import software.amazon.smithy.model.traits.HttpApiKeyAuthTrait;
+import software.amazon.smithy.model.validation.AbstractValidator;
+import software.amazon.smithy.model.validation.ValidationEvent;
+
+/**
+ * Validates that if an HttpApiKeyAuth trait's scheme field is present then
+ * the 'in' field must specify "header".
+ */
+public final class HttpApiKeyAuthTraitValidator extends AbstractValidator {
+    @Override
+    public List<ValidationEvent> validate(Model model) {
+        Set<ServiceShape> serviceShapesWithTrait = model.getServiceShapesWithTrait(HttpApiKeyAuthTrait.class);
+        List<ValidationEvent> events = new ArrayList<>();
+
+        for (ServiceShape serviceShape:serviceShapesWithTrait) {
+            HttpApiKeyAuthTrait trait = serviceShape.expectTrait(HttpApiKeyAuthTrait.class);
+            trait.getScheme().ifPresent(scheme -> {
+                if (trait.getIn() != HttpApiKeyAuthTrait.Location.HEADER) {
+                    events.add(error(serviceShape,
+                            "httpApiKeyAuth trait must use in=\"header\" when scheme is specified."));
+                }
+            });
+        }
+
+        return events;
+    }
+}

smithy-model/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator

@@ -5,6 +5,7 @@ software.amazon.smithy.model.validation.validators.EventPayloadTraitValidator
 software.amazon.smithy.model.validation.validators.ExamplesTraitValidator
 software.amazon.smithy.model.validation.validators.ExclusiveStructureMemberTraitValidator
 software.amazon.smithy.model.validation.validators.HostLabelTraitValidator
+software.amazon.smithy.model.validation.validators.HttpApiKeyAuthTraitValidator
 software.amazon.smithy.model.validation.validators.HttpBindingsMissingValidator
 software.amazon.smithy.model.validation.validators.HttpChecksumTraitValidator
 software.amazon.smithy.model.validation.validators.HttpHeaderTraitValidator

smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude.smithy

@@ -196,6 +196,9 @@ structure httpApiKeyAuth {
     /// can be set to `"header"` or `"query"`.
     @required
     in: HttpApiKeyLocations,
+
+    /// Defines an ApiKey scheme when Authorization header is used
+    scheme: NonEmptyString,
 }
 
 @private

smithy-model/src/test/java/software/amazon/smithy/model/traits/HttpApiKeyAuthTraitTest.java

@@ -18,6 +18,7 @@
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.instanceOf;
+import static org.hamcrest.Matchers.is;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.util.Optional;
@@ -39,6 +40,7 @@ public void loadsTraitWithHeader() {
         assertThat(trait.get(), instanceOf(HttpApiKeyAuthTrait.class));
         HttpApiKeyAuthTrait auth = (HttpApiKeyAuthTrait) trait.get();
 
+        assertThat(auth.getScheme().isPresent(), is(Boolean.FALSE));
         assertThat(auth.getName(), equalTo("X-Foo"));
         assertThat(auth.getIn(), equalTo(HttpApiKeyAuthTrait.Location.HEADER));
         assertThat(auth.toNode(), equalTo(node));
@@ -57,6 +59,47 @@ public void loadsTraitWithQuery() {
         assertThat(trait.get(), instanceOf(HttpApiKeyAuthTrait.class));
         HttpApiKeyAuthTrait auth = (HttpApiKeyAuthTrait) trait.get();
 
+        assertThat(auth.getScheme().isPresent(), is(Boolean.FALSE));
+        assertThat(auth.getName(), equalTo("blerg"));
+        assertThat(auth.getIn(), equalTo(HttpApiKeyAuthTrait.Location.QUERY));
+        assertThat(auth.toNode(), equalTo(node));
+        assertThat(auth.toBuilder().build(), equalTo(auth));
+    }
+
+    @Test
+    public void loadsTraitWithHeaderAndScheme() {
+        TraitFactory provider = TraitFactory.createServiceFactory();
+        ObjectNode node = Node.objectNode()
+                .withMember("scheme", "fenty")
+                .withMember("name", "X-Foo")
+                .withMember("in", "header");
+        Optional<Trait> trait = provider.createTrait(
+                HttpApiKeyAuthTrait.ID, ShapeId.from("ns.qux#foo"), node);
+        assertTrue(trait.isPresent());
+        assertThat(trait.get(), instanceOf(HttpApiKeyAuthTrait.class));
+        HttpApiKeyAuthTrait auth = (HttpApiKeyAuthTrait) trait.get();
+
+        assertThat(auth.getScheme().get(), equalTo("fenty"));
+        assertThat(auth.getName(), equalTo("X-Foo"));
+        assertThat(auth.getIn(), equalTo(HttpApiKeyAuthTrait.Location.HEADER));
+        assertThat(auth.toNode(), equalTo(node));
+        assertThat(auth.toBuilder().build(), equalTo(auth));
+    }
+
+    @Test
+    public void loadsTraitWithQueryAndScheme() {
+        TraitFactory provider = TraitFactory.createServiceFactory();
+        ObjectNode node = Node.objectNode()
+                .withMember("scheme", "fenty")
+                .withMember("name", "blerg")
+                .withMember("in", "query");
+        Optional<Trait> trait = provider.createTrait(
+                HttpApiKeyAuthTrait.ID, ShapeId.from("ns.qux#foo"), node);
+        assertTrue(trait.isPresent());
+        assertThat(trait.get(), instanceOf(HttpApiKeyAuthTrait.class));
+        HttpApiKeyAuthTrait auth = (HttpApiKeyAuthTrait) trait.get();
+
+        assertThat(auth.getScheme().get(), equalTo("fenty"));
         assertThat(auth.getName(), equalTo("blerg"));
         assertThat(auth.getIn(), equalTo(HttpApiKeyAuthTrait.Location.QUERY));
         assertThat(auth.toNode(), equalTo(node));