Add an OpenAPI specification format specifier to prevent unnecessarily downloading the service contract (#504)

* #499 - Prevent crash when no products are associated with a particular api.

* Do *not* unnecessarily download the OpenAPI definition.

Co-authored-by: Maxime LABELLE <maxime.labelle@chanel.com>
Co-authored-by: RupengLiu <rliu1211@terpmail.umd.edu>

Author: 3 people

src/APIM_ARMTemplate/README.md

@@ -48,6 +48,7 @@ The utility requires one argument, --configFile, which points to a yaml file tha
 | serviceUrl            | string                | No                    | Absolute URL of the backend service implementing this API.                                 |
 | type                  | enum                  | No                    | Type of API. - http or soap                      |
 | openApiSpec           | string                | Yes                   | Location of the Open API Spec file. Can be url or local file.                          |
+| openApiSpecFormat           | string                | No                   | Format of the API definition. When the `openApiSpec` property refers to a local file, the program will infer the format if this property is omitted. If the `openApiSpec` property refers to a url, you can prevent downloading the API definition by specifying this property. Valid values are `Swagger` (JSON), `Swagger_Json`, `OpenApi20` (YAML), `OpenApi20_Yaml`, `OpenApi20_Json`, `OpenApi30` (YAML), `OpenApi30_Yaml`, or `OpenApi30_Json`.
 | policy                | string                | No                    | Location of the API policy XML file. Can be url or local file.                          |
 | suffix                | string                | Yes                    | Relative URL uniquely identifying this API and all of its resource paths within the API Management service instance. It is appended to the API endpoint base URL specified during the service instance creation to form a public URL for this API.                       |
 | subscriptionRequired  | boolean               | No                    | Specifies whether an API or Product subscription is required for accessing the API.                         |
@@ -170,6 +171,7 @@ apis:
       description: myFirstAPI
       serviceUrl: http://myApiBackendUrl.com
       openApiSpec: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFile\OpenApiSpecs\swaggerPetstore.json
+      openApiSpecFormat: swagger
       policy: C:\Users\myUsername\Projects\azure-api-management-devops-example\src\APIM_ARMTemplate\apimtemplate\Creator\ExampleFiles\XMLPolicies\apiPolicyHeaders.xml
       suffix: conf
       subscriptionRequired: true

src/APIM_ARMTemplate/apimtemplate/Creator/Models/CreatorConfiguration.cs

@@ -53,6 +53,8 @@ public class APIConfig
         public string type { get; set; }
         // openApiSpec file location (local or url), used to build protocols, value, and format from APITemplateResource schema
         public string openApiSpec { get; set; }
+        // format of the API definition.
+        public OpenApiSpecFormat openApiSpecFormat { get; set;  }
         // policy file location (local or url)
         public string policy { get; set; }
         // used to buld path from APITemplateResource schema
@@ -74,6 +76,22 @@ public class APIConfig
         // does not currently include subscriptionKeyParameterNames, sourceApiId, and wsdlSelector from APITemplateResource schema
     }
 
+    public enum OpenApiSpecFormat
+    {
+        Unspecified,
+
+        Swagger,
+        Swagger_Json = Swagger,
+
+        OpenApi20,
+        OpenApi20_Yaml = OpenApi20,
+        OpenApi20_Json,
+
+        OpenApi30,
+        OpenApi30_Yaml = OpenApi30,
+        OpenApi30_Json,
+    }
+
     public class OperationsConfig
     {
         // policy file location (local or url)

src/APIM_ARMTemplate/apimtemplate/Creator/TemplateCreators/APITemplateCreator.cs

@@ -172,35 +172,43 @@ public async Task<APITemplateResource> CreateAPITemplateResourceAsync(APIConfig
                 string value;
 
                 // determine if the open api spec is remote or local, yaml or json
-                Uri uriResult;
-                string fileContents = await this.fileReader.RetrieveFileContentsAsync(api.openApiSpec);
-                bool isJSON = this.fileReader.isJSON(fileContents);
-                bool isUrl = Uri.TryCreate(api.openApiSpec, UriKind.Absolute, out uriResult) && (uriResult.Scheme == Uri.UriSchemeHttp || uriResult.Scheme == Uri.UriSchemeHttps);
+                bool isJSON = false;
+                bool isUrl = IsUri(api, out var _);
+
+                string fileContents = null;
+                if (!isUrl || api.openApiSpecFormat == OpenApiSpecFormat.Unspecified)
+                    fileContents = await this.fileReader.RetrieveFileContentsAsync(api.openApiSpec);
 
                 value = isUrl
                     ? api.openApiSpec
                     : fileContents
                     ;
 
                 bool isVersionThree = false;
-                if (isJSON == true)
+                if (api.openApiSpecFormat == OpenApiSpecFormat.Unspecified)
                 {
-                    // open api spec is remote json file, use swagger-link-json for v2 and openapi-link for v3
-                    OpenAPISpecReader openAPISpecReader = new OpenAPISpecReader();
-                    isVersionThree = await openAPISpecReader.isJSONOpenAPISpecVersionThreeAsync(api.openApiSpec);
+                    isJSON = this.fileReader.isJSON(fileContents);
+
+                    if (isJSON == true)
+                    {
+                        var openAPISpecReader = new OpenAPISpecReader();
+                        isVersionThree = await openAPISpecReader.isJSONOpenAPISpecVersionThreeAsync(api.openApiSpec);
+                    }
+                    format = GetOpenApiSpecFormat(isUrl, isJSON, isVersionThree);
                 }
 
-                format = isUrl
-                    ? (isJSON ? (isVersionThree ? "openapi-link" : "swagger-link-json") : "openapi-link")
-                    : (isJSON ? (isVersionThree ? "openapi+json" : "swagger-json") : "openapi")
-                    ;
+                else
+                {
+                    isJSON = IsOpenApiSpecJson(api.openApiSpecFormat);
+                    format = GetOpenApiSpecFormat(isUrl, api.openApiSpecFormat);
+                }
 
                 // if the title needs to be modified
                 // we need to embed the OpenAPI definition
 
                 if (!string.IsNullOrEmpty(api.displayName))
                 {
-                    format = (isJSON ? (isVersionThree ? "openapi+json" : "swagger-json") : "openapi");
+                    format = GetOpenApiSpecFormat(false, isJSON, isVersionThree);
 
                     // download definition
 
@@ -217,6 +225,7 @@ public async Task<APITemplateResource> CreateAPITemplateResourceAsync(APIConfig
                         .GetDefinition()
                         ;
                 }
+
                 // set the version set id
                 if (api.apiVersionSetId != null)
                 {
@@ -234,6 +243,62 @@ public async Task<APITemplateResource> CreateAPITemplateResourceAsync(APIConfig
             return apiTemplateResource;
         }
 
+        private static string GetOpenApiSpecFormat(bool isUrl, bool isJSON, bool isVersionThree)
+        {
+            return isUrl
+                ? (isJSON ? (isVersionThree ? "openapi-link" : "swagger-link-json") : "openapi-link")
+                : (isJSON ? (isVersionThree ? "openapi+json" : "swagger-json") : "openapi");
+        }
+
+        private static string GetOpenApiSpecFormat(bool isUrl, OpenApiSpecFormat openApiSpecFormat)
+        {
+            switch (openApiSpecFormat)
+            {
+                case OpenApiSpecFormat.Swagger_Json:
+                    return isUrl ? "swagger-link-json" : "swagger-json";
+
+                case OpenApiSpecFormat.OpenApi20_Yaml:
+                    return isUrl ? "openapi-link" : "openapi";
+
+                case OpenApiSpecFormat.OpenApi20_Json:
+                    return isUrl ? "openapi-link" : "swagger-json";
+
+                case OpenApiSpecFormat.OpenApi30_Yaml:
+                    return isUrl ? "openapi-link" : "openapi";
+
+                case OpenApiSpecFormat.OpenApi30_Json:
+                    return isUrl ? "openapi-link" : "openapi+json";
+
+                default:
+                    throw new NotSupportedException();
+            }
+        }
+        private static bool IsOpenApiSpecJson(OpenApiSpecFormat openApiSpecFormat)
+        {
+            switch (openApiSpecFormat)
+            {
+                case OpenApiSpecFormat.Swagger_Json:
+                case OpenApiSpecFormat.OpenApi20_Json:
+                case OpenApiSpecFormat.OpenApi30_Json:
+                    return true;
+
+                case OpenApiSpecFormat.OpenApi20_Yaml:
+                case OpenApiSpecFormat.OpenApi30_Yaml:
+                    return false;
+
+                default:
+                    throw new NotSupportedException();
+            }
+        }
+
+        private static bool IsUri(APIConfig api, out Uri uriResult)
+        {
+            return
+                Uri.TryCreate(api.openApiSpec, UriKind.Absolute, out uriResult) &&
+                (uriResult.Scheme == Uri.UriSchemeHttp || uriResult.Scheme == Uri.UriSchemeHttps)
+                ;
+        }
+
         public static string MakeResourceName(APIConfig api)
         {
             return $"[concat(parameters('{ParameterNames.ApimServiceName}'), '/{api.name}')]";