Refactoring Open API Info Metadata (#88)

Author: justinyoo

.github/workflows/build.yaml

@@ -39,7 +39,7 @@ jobs:
       shell: pwsh
       run: |
         dir
-        msbuild . /p:Configuration=Debug /p:Verbosity=minimal
+        dotnet build . -c Debug -v minimal
 
     - name: Test solution
       shell: pwsh

.github/workflows/pr.yaml

@@ -37,10 +37,10 @@ jobs:
       shell: pwsh
       run: |
         dir
-        msbuild . /p:Configuration=Release /p:Verbosity=minimal
+        dotnet build . -c Debug -v minimal
 
     - name: Test solution
       shell: pwsh
       run: |
         dir
-        dotnet test . -c Release
+        dotnet test . -c Debug

docs/app-settings.md

@@ -3,3 +3,15 @@
 ![Build and Test](https://github.com/aliencube/AzureFunctions.Extensions/workflows/Build%20and%20Test/badge.svg) [![](https://img.shields.io/nuget/dt/Aliencube.AzureFunctions.Extensions.Configuration.AppSettings.svg)](https://www.nuget.org/packages/Aliencube.AzureFunctions.Extensions.Configuration.AppSettings/) [![](https://img.shields.io/nuget/v/Aliencube.AzureFunctions.Extensions.Configuration.AppSettings.svg)](https://www.nuget.org/packages/Aliencube.AzureFunctions.Extensions.Configuration.AppSettings/)
 
 This is a base app settings environment variables deserialised. This MUST be inherited for use.
+
+```csharp
+public abstract class OpenApiAppSettingsBase : AppSettingsBase
+{
+    public OpenApiAppSettingsBase()
+        : base()
+    {
+        ...
+    }
+    ...
+}
+```

docs/dependency-injection.md

@@ -12,15 +12,23 @@ This is only applicable to Azure Functions V2, as V2 runtime now take out the `s
 
 ### `StartUp` ###
 
-In order to use dependency injections, all dependencies should be registered through the `StartUp` class implementing the `IWebJobsStartup` interface.
+In order to use dependency injections, all dependencies should be registered through the `StartUp` class inheriting the `FunctionsStartup` class.
 
 ```csharp
-[assembly: WebJobsStartup(typeof(StartUp))]
+[assembly: FunctionsStartup(typeof(Aliencube.AzureFunctions.FunctionAppV2.StartUp))]
 namespace Aliencube.AzureFunctions.FunctionAppV2
 {
-    public class StartUp : IWebJobsStartup
+    public class AppSettings : AppSettingsBase
     {
-        public void Configure(IWebJobsBuilder builder)
+        public AppSettings()
+            : base()
+        {
+        }
+    }
+
+    public class StartUp : FunctionsStartup
+    {
+        public override void Configure(IFunctionsHostBuilder builder)
         {
             builder.Services.AddSingleton<AppSettings>();
 
@@ -73,6 +81,14 @@ For Azure Function V1, the most efficient way for dependency injection would be
 In order to use dependency injection, all dependencies should be registered beforehand. The `Module` class needs to be inherited then all dependencies are registered within the `Load(IServiceCollection services)` method.
 
 ```csharp
+public class AppSettings : AppSettingsBase
+{
+    public AppSettings()
+        : base()
+    {
+    }
+}
+
 public class StartUp : Module
 {
     public override void Load(IServiceCollection services)

docs/openapi.md

@@ -41,13 +41,16 @@ public static async Task<IActionResult> RenderSwaggerDocument(
     [HttpTrigger(AuthorizationLevel.Function, "get", Route = "swagger.json")] HttpRequest req,
     ILogger log)
 {
-    var settings = new AppSettings();
+    var openApiInfo = OpenApiInfoResolver.Resolve();
+    var host = HostJsonResolver.Resolve();
+    var httpSettings = host.GetHttpSettings();
+
     var filter = new RouteConstraintFilter();
     var helper = new DocumentHelper(filter);
     var document = new Document(helper);
     var result = await document.InitialiseDocument()
-                               .AddMetadata(settings.OpenApiInfo)
-                               .AddServer(req, settings.HttpSettings.RoutePrefix)
+                               .AddMetadata(openApiInfo)
+                               .AddServer(req, httpSettings.RoutePrefix)
                                .Build(Assembly.GetExecutingAssembly(), new CamelCaseNamingStrategy())
                                .RenderAsync(OpenApiSpecVersion.OpenApi2_0, OpenApiFormat.Json)
                                .ConfigureAwait(false);
@@ -76,12 +79,16 @@ public static async Task<IActionResult> RenderSwaggerUI(
     [HttpTrigger(AuthorizationLevel.Function, "get", Route = "swagger/ui")] HttpRequest req,
     ILogger log)
 {
-    var settings = new AppSettings();
+    var openApiInfo = OpenApiInfoResolver.Resolve();
+    var host = HostJsonResolver.Resolve();
+    var httpSettings = host.GetHttpSettings();
+    var swaggerAuthKey = ConfigurationResolver.GetValue<string>("OpenApi:ApiKey");
+
     var ui = new SwaggerUI();
-    var result = await ui.AddMetadata(settings.OpenApiInfo)
-                         .AddServer(req, settings.HttpSettings.RoutePrefix)
+    var result = await ui.AddMetadata(openApiInfo)
+                         .AddServer(req, httpSettings.RoutePrefix)
                          .BuildAsync()
-                         .RenderAsync("swagger.json", settings.SwaggerAuthKey)
+                         .RenderAsync("swagger.json", swaggerAuthKey)
                          .ConfigureAwait(false);
     var response = new ContentResult()
                        {
@@ -95,7 +102,71 @@ public static async Task<IActionResult> RenderSwaggerUI(
 ```
 
 
-## App Settings ##
+## Open API Metadata ##
+
+To generate an Open API document, [OpenApiInfo object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#infoObject) needs to be defined. This information can be declared in three places &ndash; `host.json`, `openapisettings.json` or `local.settings.json`.
+
+This library looks for the information in the following order:
+
+1. `host.json`
+2. `openapisettings.json`
+3. `local.settings.json` or App Settings blade
+
+
+### `host.json` ###
+
+Although it has not been officially accepted to be a part of `host.json`, the Open API metadata still can be stored in it like:
+
+```json
+{
+  ...
+  "openApi": {
+    "info": {
+      "version": "3.0.0",
+      "title": "Open API Sample on Azure Functions",
+      "description": "A sample API that runs on Azure Functions 3.x using Open API specification - from **host. json**.",
+      "termsOfService": "https://github.com/aliencube/AzureFunctions.Extensions",
+      "contact": {
+        "name": "Aliencube Community",
+        "email": "[email protected]",
+        "url": "https://github.com/aliencube/AzureFunctions.Extensions/issues"
+      },
+      "license": {
+        "name": "MIT",
+        "url": "http://opensource.org/licenses/MIT"
+      }
+    }
+  }
+  ...
+}
+```
+
+
+### `openapisettings.json` ###
+
+The Open API metadata can be defined in a separate file, `openapisettings.json` like:
+
+```json
+{
+  "info": {
+    "version": "3.0.0",
+    "title": "Open API Sample on Azure Functions",
+    "description": "A sample API that runs on Azure Functions 3.x using Open API specification - from  **openapisettings.json**.",
+    "termsOfService": "https://github.com/aliencube/AzureFunctions.Extensions",
+    "contact": {
+      "name": "Aliencube Community",
+      "email": "[email protected]",
+      "url": "https://github.com/aliencube/AzureFunctions.Extensions/issues"
+    },
+    "license": {
+      "name": "MIT",
+      "url": "http://opensource.org/licenses/MIT"
+    }
+  }
+}
+```
+
+### `local.settings.json` or App Settings ###
 
 On either your `local.settings.json` or App Settings on Azure Functions instance, those details should be set up to render Open API metadata:
 

src/Aliencube.AzureFunctions.Extensions.Configuration.AppSettings/Aliencube.AzureFunctions.Extensions.Configuration.AppSettings.csproj

@@ -4,6 +4,7 @@
     <TargetFrameworks>net461;netstandard2.0</TargetFrameworks>
     <IsPackable>true</IsPackable>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <PackageId>Aliencube.AzureFunctions.Extensions.Configuration.AppSettings</PackageId>
     <Owners>Aliencube</Owners>

src/Aliencube.AzureFunctions.Extensions.Configuration.AppSettings/AppSettingsBase.cs

@@ -1,12 +1,7 @@
-using System;
-using System.IO;
-using System.Linq;
-using System.Reflection;
+using Aliencube.AzureFunctions.Extensions.Configuration.AppSettings.Resolvers;
 
 using Microsoft.Extensions.Configuration;
 
-using OperatingSystem = Aliencube.AzureFunctions.Extensions.Configuration.AppSettings.Extensions.OperationSystem;
-
 namespace Aliencube.AzureFunctions.Extensions.Configuration.AppSettings
 {
     /// <summary>
@@ -19,9 +14,7 @@ public abstract class AppSettingsBase
         /// </summary>
         protected AppSettingsBase()
         {
-            this.Config = new ConfigurationBuilder()
-                              .AddEnvironmentVariables()
-                              .Build();
+            this.Config = ConfigurationResolver.Resolve();
         }
 
         /// <summary>
@@ -35,22 +28,7 @@ protected AppSettingsBase()
         /// <returns></returns>
         protected string GetBasePath()
         {
-            var location = Assembly.GetExecutingAssembly().Location;
-            var segments = location.Split(new[] { Path.DirectorySeparatorChar }, StringSplitOptions.RemoveEmptyEntries).ToList();
-            var basePath = string.Join(Path.DirectorySeparatorChar.ToString(), segments.Take(segments.Count - 2));
-
-            if (!OperatingSystem.IsWindows())
-            {
-                basePath = $"/{basePath}";
-            }
-#if NET461
-            var scriptRootPath = this.Config.GetValue<string>("AzureWebJobsScriptRoot");
-            if (!string.IsNullOrWhiteSpace(scriptRootPath))
-            {
-                basePath = scriptRootPath;
-            }
-#endif
-            return basePath;
+            return ConfigurationResolver.GetBasePath(this.Config);
         }
     }
 }

src/Aliencube.AzureFunctions.Extensions.Configuration.AppSettings/Resolvers/ConfigurationResolver.cs

@@ -0,0 +1,85 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+
+using Microsoft.Extensions.Configuration;
+
+using OperatingSystem = Aliencube.AzureFunctions.Extensions.Configuration.AppSettings.Extensions.OperationSystem;
+
+namespace Aliencube.AzureFunctions.Extensions.Configuration.AppSettings.Resolvers
+{
+    /// <summary>
+    /// This represents the resolver entity for configuration.
+    /// </summary>
+    public static class ConfigurationResolver
+    {
+        /// <summary>
+        /// Gets the <see cref="IConfiguration"/> instance from the environment variables - either local.settings.json or App Settings blade.
+        /// </summary>
+        public static IConfiguration Resolve()
+        {
+            var config = new ConfigurationBuilder()
+                             .AddEnvironmentVariables()
+                             .Build();
+
+            return config;
+        }
+
+        /// <summary>
+        /// Gets the configuration value.
+        /// </summary>
+        /// <typeparam name="T">Type of return value.</typeparam>
+        /// <param name="key">Key for lookup.</param>
+        /// <param name="config"><see cref="IConfiguration"/> instance from the environment variables - either local.settings.json or App Settings blade.</param>
+        /// <returns>Returns the value.</returns>
+        public static T GetValue<T>(string key, IConfiguration config = null)
+        {
+            if (config == null)
+            {
+                config = Resolve();
+            }
+
+            var value = config.GetValue<T>(key);
+
+            return value;
+        }
+
+        /// <summary>
+        /// Gets the base path of the executing Azure Functions assembly.
+        /// </summary>
+        /// <param name="environmentVariables"><see cref="IConfiguration"/> instance representing environment variables from either local.settings.json or App Settings blade.</param>
+        /// <returns>Returns the base path of the executing Azure Functions assembly.</returns>
+        public static string GetBasePath(IConfiguration environmentVariables)
+        {
+            var location = Assembly.GetExecutingAssembly().Location;
+            var segments = location.Split(new[] { Path.DirectorySeparatorChar }, StringSplitOptions.RemoveEmptyEntries).ToList();
+            var basePath = string.Join(Path.DirectorySeparatorChar.ToString(), segments.Take(CountDirectories(segments)));
+
+            if (!OperatingSystem.IsWindows())
+            {
+                basePath = $"/{basePath}";
+            }
+#if NET461
+            var scriptRootPath = environmentVariables.GetValue<string>("AzureWebJobsScriptRoot");
+            if (!string.IsNullOrWhiteSpace(scriptRootPath))
+            {
+                basePath = scriptRootPath;
+            }
+#endif
+            return basePath;
+        }
+
+        private static int CountDirectories(List<string> segments)
+        {
+            var bin = segments[segments.Count - 2];
+            if (bin == "bin")
+            {
+                return segments.Count - 2;
+            }
+
+            return segments.Count - 1;
+        }
+    }
+}

src/Aliencube.AzureFunctions.Extensions.Configuration.Json/Aliencube.AzureFunctions.Extensions.Configuration.Json.csproj

@@ -4,6 +4,7 @@
     <TargetFramework>net461</TargetFramework>
     <IsPackable>true</IsPackable>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <PackageId>Aliencube.AzureFunctions.Extensions.Configuration.Json</PackageId>
     <Owners>Aliencube</Owners>

src/Aliencube.AzureFunctions.Extensions.DependencyInjection/Aliencube.AzureFunctions.Extensions.DependencyInjection.csproj

@@ -4,6 +4,7 @@
     <TargetFrameworks>net461;netstandard2.0</TargetFrameworks>
     <IsPackable>true</IsPackable>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
     <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
     <PackageId>Aliencube.AzureFunctions.Extensions.DependencyInjection</PackageId>
     <Owners>Aliencube</Owners>