.Net: Issue 11562 (add plugin description)

dotnet/src/Functions/Functions.OpenApi.Extensions/Extensions/ApiManifestKernelExtensions.cs

@@ -39,8 +39,27 @@ public static async Task<KernelPlugin> ImportPluginFromApiManifestAsync(
         string filePath,
         ApiManifestPluginParameters? pluginParameters = null,
         CancellationToken cancellationToken = default)
+        => await kernel.ImportPluginFromApiManifestAsync(pluginName, filePath, null, pluginParameters, cancellationToken).ConfigureAwait(false);
+
+    /// <summary>
+    /// Imports a plugin from an API manifest asynchronously.
+    /// </summary>
+    /// <param name="kernel">The kernel instance.</param>
+    /// <param name="pluginName">The name of the plugin.</param>
+    /// <param name="filePath">The file path of the API manifest.</param>
+    /// <param name="description">The description of the plugin.</param>
+    /// <param name="pluginParameters">Optional parameters for the plugin setup.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>The imported plugin.</returns>
+    public static async Task<KernelPlugin> ImportPluginFromApiManifestAsync(
+        this Kernel kernel,
+        string pluginName,
+        string filePath,
+        string? description,
+        ApiManifestPluginParameters? pluginParameters = null,
+        CancellationToken cancellationToken = default)
     {
-        KernelPlugin plugin = await kernel.CreatePluginFromApiManifestAsync(pluginName, filePath, pluginParameters, cancellationToken).ConfigureAwait(false);
+        KernelPlugin plugin = await kernel.CreatePluginFromApiManifestAsync(pluginName, filePath, description, pluginParameters, cancellationToken).ConfigureAwait(false);
         kernel.Plugins.Add(plugin);
         return plugin;
     }
@@ -60,6 +79,25 @@ public static async Task<KernelPlugin> CreatePluginFromApiManifestAsync(
         string filePath,
         ApiManifestPluginParameters? pluginParameters = null,
         CancellationToken cancellationToken = default)
+        => await kernel.CreatePluginFromApiManifestAsync(pluginName, filePath, null, pluginParameters, cancellationToken).ConfigureAwait(false);
+
+    /// <summary>
+    /// Creates a kernel plugin from an API manifest file asynchronously.
+    /// </summary>
+    /// <param name="kernel">The kernel instance.</param>
+    /// <param name="pluginName">The name of the plugin.</param>
+    /// <param name="filePath">The file path of the API manifest.</param>
+    /// <param name="description">The description of the plugin.</param>
+    /// <param name="pluginParameters">Optional parameters for the plugin setup.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the created kernel plugin.</returns>
+    public static async Task<KernelPlugin> CreatePluginFromApiManifestAsync(
+        this Kernel kernel,
+        string pluginName,
+        string filePath,
+        string? description,
+        ApiManifestPluginParameters? pluginParameters = null,
+        CancellationToken cancellationToken = default)
     {
         Verify.NotNull(kernel);
         Verify.ValidPluginName(pluginName, kernel.Plugins);
@@ -187,6 +225,6 @@ await DocumentLoader.LoadDocumentFromUriAsStreamAsync(new Uri(apiDescriptionUrl)
             }
         }
 
-        return KernelPluginFactory.CreateFromFunctions(pluginName, null, functions);
+        return KernelPluginFactory.CreateFromFunctions(pluginName, description, functions);
     }
 }

dotnet/src/Functions/Functions.UnitTests/Functions.UnitTests.csproj

@@ -73,6 +73,9 @@
     <EmbeddedResource Include="OpenApi\TestPlugins\multipart-form-data.json" />
   </ItemGroup>
   <ItemGroup>
+    <None Update="OpenApi\TestPlugins\example-apimanifest.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
     <None Update="OpenApi\TestPlugins\messages-apiplugin.json">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>

dotnet/src/Functions/Functions.UnitTests/OpenApi/Extensions/ApiManifestKernelExtensionsTests.cs

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.IO;
+using System.Threading.Tasks;
+using Microsoft.SemanticKernel;
+using Xunit;
+
+namespace SemanticKernel.Functions.UnitTests.OpenApi.Extensions;
+public sealed class ApiManifestKernelExtensionsTests
+{
+    [Fact]
+    public async Task ItCanCreatePluginFromApiManifestAsync()
+    {
+        // Act
+        var kernel = new Kernel();
+        var testPluginsDir = Path.Combine(Directory.GetCurrentDirectory(), "OpenApi", "TestPlugins");
+        var manifestFilePath = Path.Combine(testPluginsDir, "example-apimanifest.json");
+
+        // Arrange
+        var plugin = await kernel.CreatePluginFromApiManifestAsync("ApiManifestPlugin", manifestFilePath);
+
+        // Assert
+        Assert.NotNull(plugin);
+        Assert.Equal(3, plugin.FunctionCount);
+    }
+
+    [Fact]
+    public async Task ItCanCreatePluginFromApiManifestWithDescriptionParameterAsync()
+    {
+        // Act
+        var kernel = new Kernel();
+        var testPluginsDir = Path.Combine(Directory.GetCurrentDirectory(), "OpenApi", "TestPlugins");
+        var manifestFilePath = Path.Combine(testPluginsDir, "example-apimanifest.json");
+        var description = "My plugin description";
+
+        // Arrange
+        var plugin = await kernel.CreatePluginFromApiManifestAsync("ApiManifestPlugin", manifestFilePath, description);
+
+        // Assert
+        Assert.NotNull(plugin);
+        Assert.Equal(description, plugin.Description);
+    }
+
+    [Fact]
+    public async Task ItCanCreatePluginFromApiManifestWithEmptyDescriptionParameterAsync()
+    {
+        // Act
+        var kernel = new Kernel();
+        var testPluginsDir = Path.Combine(Directory.GetCurrentDirectory(), "OpenApi", "TestPlugins");
+        var manifestFilePath = Path.Combine(testPluginsDir, "example-apimanifest.json");
+
+        // Arrange
+        var plugin = await kernel.CreatePluginFromApiManifestAsync("ApiManifestPlugin", manifestFilePath, description: null);
+
+        // Assert
+        Assert.NotNull(plugin);
+        Assert.Empty(plugin.Description);
+    }
+
+    [Fact]
+    public async Task ItCanImportPluginFromApiManifestAsync()
+    {
+        // Act
+        var kernel = new Kernel();
+        var testPluginsDir = Path.Combine(Directory.GetCurrentDirectory(), "OpenApi", "TestPlugins");
+        var manifestFilePath = Path.Combine(testPluginsDir, "example-apimanifest.json");
+
+        // Arrange
+        var plugin = await kernel.ImportPluginFromApiManifestAsync("ApiManifestPlugin", manifestFilePath);
+
+        // Assert
+        Assert.NotNull(plugin);
+        Assert.Equal(3, plugin.FunctionCount);
+        Assert.Single(kernel.Plugins);
+    }
+
+    [Fact]
+    public async Task ItCanImportPluginFromApiManifestWithDescriptionParameterAsync()
+    {
+        // Act
+        var kernel = new Kernel();
+        var testPluginsDir = Path.Combine(Directory.GetCurrentDirectory(), "OpenApi", "TestPlugins");
+        var manifestFilePath = Path.Combine(testPluginsDir, "example-apimanifest.json");
+        var description = "My plugin description";
+
+        // Arrange
+        var plugin = await kernel.ImportPluginFromApiManifestAsync("ApiManifestPlugin", manifestFilePath, description);
+
+        // Assert
+        Assert.NotNull(plugin);
+        Assert.Equal(description, plugin.Description);
+    }
+}

dotnet/src/Functions/Functions.UnitTests/OpenApi/TestPlugins/example-apimanifest.json

@@ -0,0 +1,46 @@
+{
+  "applicationName": "My Application",
+  "publisher": {
+    "name": "Alice",
+    "contactEmail": "[email protected]"
+  },
+  "apiDependencies": {
+    "moostodon": {
+      "apiDescriptionUrl": "https://raw.githubusercontent.com/APIPatterns/Moostodon/main/spec/tsp-output/%40typespec/openapi3/openapi.yaml",
+      "auth": {
+        "clientIdentifier": "some-uuid-here",
+        "access": [
+          "resourceA.ReadWrite",
+          "resourceB.ReadWrite",
+          "resourceB.Read"
+        ]
+      },
+      "requests": [
+        {
+          "method": "GET",
+          "uriTemplate": "/api/v1/accounts/search"
+        },
+        {
+          "method": "GET",
+          "uriTemplate": "/api/v1/accounts/{id}"
+        }
+      ]
+    },
+    "MicrosoftGraph": {
+      "apiDescriptionUrl": "https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-powershell/dev/openApiDocs/v1.0/DirectoryObjects.yml",
+      "auth": {
+        "clientIdentifier": "some-uuid-here",
+        "access": [
+          "resourceA.ReadWrite",
+          "resourceB.Read"
+        ]
+      },
+      "requests": [
+        {
+          "method": "GET",
+          "uriTemplate": "/directoryObjects/{directoryObject-id}"
+        }
+      ]
+    }
+  }
+}