Improve httpApiKeyAuth description in OpenAPI

Relates to #872

Author: mtdowling

smithy-aws-apigateway-openapi/src/test/resources/software/amazon/smithy/aws/apigateway/openapi/operation-http-api-key-security.openapi.json

@@ -25,7 +25,7 @@
     "securitySchemes": {
       "api_key": {
         "type": "apiKey",
-        "description": "X-Api-Key authentication",
+        "description": "API key authentication via the 'x-api-key' header",
         "name": "x-api-key",
         "in": "header"
       }

smithy-openapi/src/main/java/software/amazon/smithy/openapi/fromsmithy/security/HttpApiKeyAuthConverter.java

@@ -40,21 +40,32 @@ public Class<HttpApiKeyAuthTrait> getAuthSchemeType() {
 
     @Override
     public SecurityScheme createSecurityScheme(Context<? extends Trait> context, HttpApiKeyAuthTrait trait) {
+        StringBuilder description = new StringBuilder()
+                .append("API key authentication via the '")
+                .append(trait.getName())
+                .append("' ");
+
+        if (trait.getIn().equals(HttpApiKeyAuthTrait.Location.QUERY)) {
+            description.append(" query string parameter");
+        } else {
+            description.append(trait.getIn());
+        }
+
         if (trait.getScheme().isPresent()) {
             return SecurityScheme.builder()
                     .type("http")
                     .scheme(trait.getScheme().get())
                     .name(trait.getName())
                     .in(trait.getIn().toString())
-                    .description("ApiKey authentication semantics via 'Authorization' header")
+                    .description(description.toString())
                     .build();
         }
 
         return SecurityScheme.builder()
                 .type("apiKey")
                 .name(trait.getName())
                 .in(trait.getIn().toString())
-                .description("X-Api-Key authentication")
+                .description(description.toString())
                 .build();
     }
 

smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/security/http-api-key-bearer-security.json

@@ -14,7 +14,7 @@
                 "smithy.api#httpApiKeyAuth": {
                     "name": "Authorization",
                     "in": "header",
-                    "scheme": "ApiKey"
+                    "scheme": "whatever-scheme-we-want"
                 }
             }
         },

smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/security/http-api-key-bearer-security.openapi.json

@@ -20,10 +20,10 @@
         "securitySchemes": {
             "smithy.api.httpApiKeyAuth": {
                 "type": "http",
-                "description": "ApiKey authentication semantics via 'Authorization' header",
+                "description": "API key authentication via the 'Authorization' header",
                 "name": "Authorization",
                 "in": "header",
-                "scheme": "ApiKey"
+                "scheme": "whatever-scheme-we-want"
             }
         }
     },

smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/security/http-api-key-security.openapi.json

@@ -20,7 +20,7 @@
         "securitySchemes": {
             "smithy.api.httpApiKeyAuth": {
                 "type": "apiKey",
-                "description": "X-Api-Key authentication",
+                "description": "API key authentication via the 'x-api-key' header",
                 "name": "x-api-key",
                 "in": "header"
             }