Refactor OpenApiSpecGeneratorPlugin and PowerPlatformOpenApiSpecGeneratorPlugin for improved operation ID and description generation; streamline prompt files for parameter and response handling; enhance API title generation logic; remove unused prompt files.

Author: ricwilson

DevProxy.Plugins/Generation/OpenApiSpecGeneratorPlugin.cs

@@ -120,7 +120,6 @@ public override async Task AfterRecordingStopAsync(RecordingArgs e)
 
         var openApiDocs = new List<OpenApiDocument>();
 
-
         foreach (var request in e.RequestLogs)
         {
             if (request.MessageType != MessageType.InterceptedResponse ||
@@ -145,17 +144,6 @@ request.Context.Session is null ||
             {
                 var pathItem = GetOpenApiPathItem(request.Context.Session);
                 var parametrizedPath = ParametrizePath(pathItem, request.Context.Session.HttpClient.Request.RequestUri);
-                var operationInfo = pathItem.Operations.First();
-                operationInfo.Value.OperationId = await GetOperationIdAsync(
-                    operationInfo.Key.ToString(),
-                    request.Context.Session.HttpClient.Request.RequestUri.GetLeftPart(UriPartial.Authority),
-                    parametrizedPath
-                );
-                operationInfo.Value.Description = await GetOperationDescriptionAsync(
-                    operationInfo.Key.ToString(),
-                    request.Context.Session.HttpClient.Request.RequestUri.GetLeftPart(UriPartial.Authority),
-                    parametrizedPath
-                );
                 await ProcessPathItemAsync(pathItem, request.Context.Session.HttpClient.Request.RequestUri, parametrizedPath);
                 AddOrMergePathItem(openApiDocs, pathItem, request.Context.Session.HttpClient.Request.RequestUri, parametrizedPath);
             }
@@ -219,10 +207,22 @@ request.Context.Session is null ||
     /// <param name="requestUri">The request URI.</param>
     /// <param name="parametrizedPath">The parametrized path string.</param>
     /// <returns>The processed OpenApiPathItem.</returns>
-    protected virtual Task ProcessPathItemAsync(OpenApiPathItem pathItem, Uri requestUri, string parametrizedPath)
+    protected virtual async Task ProcessPathItemAsync(OpenApiPathItem pathItem, Uri requestUri, string parametrizedPath)
     {
-        // By default, return the path item unchanged. Derived plugins can override to add/modify path-level data.
-        return Task.CompletedTask;
+        ArgumentNullException.ThrowIfNull(pathItem);
+        ArgumentNullException.ThrowIfNull(requestUri);
+
+        var operationInfo = pathItem.Operations.First();
+        operationInfo.Value.OperationId = await GetOperationIdAsync(
+            operationInfo.Key.ToString(),
+            requestUri.GetLeftPart(UriPartial.Authority),
+            parametrizedPath
+        );
+        operationInfo.Value.Description = await GetOperationDescriptionAsync(
+            operationInfo.Key.ToString(),
+            requestUri.GetLeftPart(UriPartial.Authority),
+            parametrizedPath
+        );
     }
 
     /// <summary>
@@ -248,7 +248,7 @@ protected virtual async Task<string> GetOperationIdAsync(string method, string s
                 { "request", $"{method.ToUpperInvariant()} {serverUrl}{parametrizedPath}" }
             });
         }
-        return id?.Response ?? $"{method}{parametrizedPath.Replace('/', '.')}";
+        return id?.Response?.Trim() ?? $"{method}{parametrizedPath.Replace('/', '.')}";
     }
 
     protected virtual async Task<string> GetOperationDescriptionAsync(string method, string serverUrl, string parametrizedPath, string promptyFile = "api_operation_description")
@@ -263,7 +263,7 @@ protected virtual async Task<string> GetOperationDescriptionAsync(string method,
                 { "request", $"{method.ToUpperInvariant()} {serverUrl}{parametrizedPath}" }
             });
         }
-        return description?.Response ?? $"{method} {parametrizedPath}";
+        return description?.Response?.Trim() ?? $"{method} {parametrizedPath}";
     }
 
     /**

DevProxy.Plugins/Generation/PowerPlatformOpenApiSpecGeneratorPlugin.cs

@@ -36,12 +36,15 @@ IConfigurationSection pluginConfigurationSection
     /// <param name="requestUri">The request URI for context.</param>
     /// <param name="parametrizedPath">The parametrized path for the operation.</param>
     /// <returns>The processed OpenAPI path item.</returns>
-    protected override async Task ProcessPathItemAsync(OpenApiPathItem pathItem, Uri requestUri, string parametrizedPath)
+    /// <exception cref="ArgumentNullException">Thrown if <paramref name="pathItem"/> or <paramref name="requestUri"/> is null.</exception>
+    protected override async Task<Task> ProcessPathItemAsync(OpenApiPathItem pathItem, Uri requestUri, string parametrizedPath)
     {
         ArgumentNullException.ThrowIfNull(pathItem);
         ArgumentNullException.ThrowIfNull(requestUri);
 
         await ProcessPathItemDetailsAsync(pathItem, requestUri, parametrizedPath);
+
+        return Task.CompletedTask;
     }
 
     /// <summary>
@@ -54,18 +57,16 @@ protected override async Task ProcessOpenApiDocumentAsync(OpenApiDocument openAp
     {
         ArgumentNullException.ThrowIfNull(openApiDoc);
         openApiDoc.Info.Contact = Configuration.Contact?.ToOpenApiContact();
-        SetTitleAndDescription(openApiDoc);
 
         // Try to get the server URL from the OpenAPI document
         var serverUrl = openApiDoc.Servers?.FirstOrDefault()?.Url;
-
         if (string.IsNullOrWhiteSpace(serverUrl))
         {
             throw new InvalidOperationException("No server URL found in the OpenAPI document. Please ensure the document contains at least one server definition.");
         }
 
-        // Asynchronously call the metadata generator
-        var metadata = await GenerateConnectorMetadataAsync(serverUrl);
+        var (apiDescription, operationDescriptions) = await SetTitleAndDescription(openApiDoc, serverUrl);
+        var metadata = await GenerateConnectorMetadataAsync(serverUrl, apiDescription, operationDescriptions);
         openApiDoc.Extensions["x-ms-connector-metadata"] = metadata;
         RemoveConnectorMetadataExtension(openApiDoc);
     }
@@ -74,32 +75,48 @@ protected override async Task ProcessOpenApiDocumentAsync(OpenApiDocument openAp
     /// Sets the OpenApi title and description in the Info area of the OpenApiDocument using LLM-generated values.
     /// </summary>
     /// <param name="openApiDoc">The OpenAPI document to process.</param>
-    private void SetTitleAndDescription(OpenApiDocument openApiDoc)
+    /// <param name="serverUrl">The server URL to use as a fallback for title and description.</param>
+    /// <returns>A tuple containing the API description and a list of operation descriptions.</returns>
+    private async Task<(string apiDescription, string operationDescriptions)> SetTitleAndDescription(OpenApiDocument openApiDoc, string serverUrl)
     {
-        // Synchronously call the async title/description generators
-        var defaultTitle = openApiDoc.Info?.Title ?? "API";
-        var defaultDescription = openApiDoc.Info?.Description ?? "API description.";
-        var title = GetOpenApiTitleAsync(defaultTitle).GetAwaiter().GetResult();
-        var description = GetOpenApiDescriptionAsync(defaultDescription).GetAwaiter().GetResult();
+        var defaultTitle = openApiDoc.Info?.Title ?? serverUrl;
+        var defaultDescription = openApiDoc.Info?.Description ?? serverUrl;
+        var operationDescriptions = string.Join(
+        Environment.NewLine,
+        openApiDoc.Paths?
+            .SelectMany(p => p.Value.Operations.Values)
+            .Select(op => op.Description)
+            .Where(desc => !string.IsNullOrWhiteSpace(desc))
+            .Distinct()
+            .Select(d => $"- {d}") ?? []
+        );
+
+        var title = await GetOpenApiTitleAsync(defaultTitle, operationDescriptions);
+        var description = await GetOpenApiDescriptionAsync(defaultDescription, operationDescriptions);
         openApiDoc.Info ??= new OpenApiInfo();
         openApiDoc.Info.Title = title;
         openApiDoc.Info.Description = description;
+
+        return (description, operationDescriptions);
     }
 
     /// <summary>
     /// Removes the x-ms-connector-metadata extension from the OpenAPI document if it exists
     /// and is empty.
     /// </summary>
     /// <param name="openApiDoc">The OpenAPI document to process.</param>
-    private async Task<string> GetOpenApiDescriptionAsync(string defaultDescription)
+    /// <param name="operationDescriptions">Operation descriptions to use for generating the OpenAPI description.</param>
+    /// <returns>The OpenAPI description generated by LLM or the default description.</returns>
+    private async Task<string> GetOpenApiDescriptionAsync(string defaultDescription, string operationDescriptions)
     {
         ILanguageModelCompletionResponse? description = null;
 
         if (await _languageModelClient.IsEnabledAsync())
         {
             description = await _languageModelClient.GenerateChatCompletionAsync("powerplatform_api_description", new()
             {
-                { "description", defaultDescription }
+                { "defaultDescription", defaultDescription },
+                { "operationDescriptions", operationDescriptions }
             });
         }
 
@@ -110,14 +127,17 @@ private async Task<string> GetOpenApiDescriptionAsync(string defaultDescription)
     /// Generates a concise and descriptive title for the OpenAPI document using LLM or fallback logic.
     /// </summary>
     /// <param name="defaultTitle">The default title to use if LLM generation fails.</param>
-    private async Task<string> GetOpenApiTitleAsync(string defaultTitle)
+    /// <param name="operationDescriptions">A list of operation descriptions for context.</param>
+    /// <returns>The generated title.</returns>
+    private async Task<string> GetOpenApiTitleAsync(string defaultTitle, string operationDescriptions)
     {
         ILanguageModelCompletionResponse? title = null;
 
         if (await _languageModelClient.IsEnabledAsync())
         {
             title = await _languageModelClient.GenerateChatCompletionAsync("powerplatform_api_title", new() {
-                { "defaultTitle", defaultTitle }
+                { "defaultTitle", defaultTitle },
+                { "operationDescriptions", operationDescriptions }
             });
         }
 
@@ -448,11 +468,13 @@ private static string GetResponsePropertyDescriptionFallback(string propertyName
     /// Generates the connector metadata OpenAPI extension array using configuration and LLM.
     /// </summary>
     /// <param name="serverUrl">The server URL for context.</param>
+    /// <param name="apiDescription">The API description for context.</param>
+    /// <param name="operationDescriptions">A list of operation descriptions for context.</param>
     /// <returns>An <see cref="OpenApiArray"/> containing connector metadata.</returns>
-    private async Task<OpenApiArray> GenerateConnectorMetadataAsync(string serverUrl)
+    private async Task<OpenApiArray> GenerateConnectorMetadataAsync(string serverUrl, string apiDescription, string operationDescriptions)
     {
-        var website = Configuration.ConnectorMetadata?.Website ?? await GetConnectorMetadataWebsiteUrlAsync(serverUrl);
-        var privacyPolicy = Configuration.ConnectorMetadata?.PrivacyPolicy ?? await GetConnectorMetadataPrivacyPolicyUrlAsync(serverUrl);
+        var website = Configuration.ConnectorMetadata?.Website ?? serverUrl;
+        var privacyPolicy = Configuration.ConnectorMetadata?.PrivacyPolicy ?? serverUrl;
 
         string categories;
         var categoriesList = Configuration.ConnectorMetadata?.Categories;
@@ -462,7 +484,7 @@ private async Task<OpenApiArray> GenerateConnectorMetadataAsync(string serverUrl
         }
         else
         {
-            categories = await GetConnectorMetadataCategoriesAsync(serverUrl, "Data");
+            categories = await GetConnectorMetadataCategoriesAsync(serverUrl, apiDescription, operationDescriptions);
         }
 
         var metadataArray = new OpenApiArray
@@ -486,70 +508,32 @@ private async Task<OpenApiArray> GenerateConnectorMetadataAsync(string serverUrl
         return metadataArray;
     }
 
-    /// <summary>
-    /// Generates the website URL for connector metadata using LLM or configuration.
-    /// </summary>
-    /// <param name="defaultUrl">The default URL to use if LLM fails.</param>
-    /// <returns>The website URL.</returns>
-    private async Task<string> GetConnectorMetadataWebsiteUrlAsync(string defaultUrl)
-    {
-        ILanguageModelCompletionResponse? response = null;
-
-        if (await _languageModelClient.IsEnabledAsync())
-        {
-            response = await _languageModelClient.GenerateChatCompletionAsync("powerplatform_api_connector_metadata_website", new()
-            {
-                { "defaultUrl", defaultUrl }
-            });
-        }
-
-        // Fallback to the default URL if the language model fails or returns no response
-        return !string.IsNullOrWhiteSpace(response?.Response) ? response.Response.Trim() : defaultUrl;
-    }
-
-    /// <summary>
-    /// Generates the privacy policy URL for connector metadata using LLM or configuration.
-    /// </summary>
-    /// <param name="defaultUrl">The default URL to use if LLM fails.</param>
-    /// <returns>The privacy policy URL.</returns>
-    private async Task<string> GetConnectorMetadataPrivacyPolicyUrlAsync(string defaultUrl)
-    {
-        ILanguageModelCompletionResponse? response = null;
-
-        if (await _languageModelClient.IsEnabledAsync())
-        {
-            response = await _languageModelClient.GenerateChatCompletionAsync("powerplatform_api_connector_metadata_privacy_policy", new()
-            {
-                { "defaultUrl", defaultUrl }
-            });
-        }
-
-        // Fallback to the default URL if the language model fails or returns no response
-        return !string.IsNullOrWhiteSpace(response?.Response) ? response.Response.Trim() : defaultUrl;
-    }
-
     /// <summary>
     /// Generates the categories for connector metadata using LLM or configuration.
     /// </summary>
     /// <param name="serverUrl">The server URL for context.</param>
-    /// <param name="defaultCategories">The default categories to use if LLM fails.</param>
-    /// <returns>The categories string.</returns>
-    private async Task<string> GetConnectorMetadataCategoriesAsync(string serverUrl, string defaultCategories)
+    /// <param name="apiDescription">The API description for context.</param>
+    /// <param name="operationDescriptions">A list of operation descriptions for context.</param>
+    /// <returns>A string containing the categories for the connector metadata.</returns>
+    /// <exception cref="InvalidOperationException">Thrown if the language model is not enabled and
+    private async Task<string> GetConnectorMetadataCategoriesAsync(string serverUrl, string apiDescription, string operationDescriptions)
     {
         ILanguageModelCompletionResponse? response = null;
 
         if (await _languageModelClient.IsEnabledAsync())
         {
             response = await _languageModelClient.GenerateChatCompletionAsync("powerplatform_api_connector_metadata_categories", new()
             {
-                { "serverUrl", serverUrl }
+                { "serverUrl", serverUrl },
+                { "apiDescription", apiDescription },
+                { "operationDescriptions", operationDescriptions }
             });
         }
 
         // If the response is 'None' or empty, return the default categories
         return !string.IsNullOrWhiteSpace(response?.Response) && response.Response.Trim() != "None"
-            ? response.Response
-            : defaultCategories;
+            ? response.Response.Trim()
+            : "Data";
     }
 
     /// <summary>

DevProxy/DevProxy.csproj

@@ -82,6 +82,9 @@
     <None Update="prompts\powerplatform_api_operation_id.prompty">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </None>
+    <None Update="prompts\powerplatform_api_operation_summary.prompty">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
     <None Update="prompts\powerplatform_api_parameter_description.prompty">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </None>

DevProxy/prompts/powerplatform_api_connector_metadata_categories.prompty

@@ -1,21 +1,27 @@
 ---
-name: OpenAPI allowed categories
-description: Determine the most appropriate categories for an API from the Microsoft Power Platform allowed list.
+name: Power Platform OpenAPI Categories
+description: Classify the API into one or more Microsoft Power Platform allowed categories based on the API metadata and server URL.
 authors:
   - Dev Proxy
 model:
   api: chat
 sample:
   request: |
     Server URL: https://api.example.com
-    Response: Data
+    API Description: A service that provides document collaboration features
+    Operation Descriptions:
+    - Share a document with another user.
+    - Retrieve a list of collaborators.
+    - Update document permissions.
+    Response: Collaboration, Content and Files
+  response: |
+    Collaboration, Content and Files
 ---
 
 system:
-You're an expert in OpenAPI and API documentation. Based on the following API metadata and the server URL, determine the most appropriate categories for the API from the allowed list of categories. If you cannot determine appropriate categories, respond with 'None'.
+You are an expert in OpenAPI and Microsoft Power Platform custom connectors. Your task is to classify an API based on its metadata and purpose using only the categories allowed by Power Platform.
 
-API Metadata:
-- Server URL: {{serverUrl}}
+These categories are used in the Power Platform custom connector metadata field `x-ms-connector-metadata.categories`.
 
 Allowed Categories:
 - AI
@@ -39,15 +45,24 @@ Allowed Categories:
 - Website
 
 Rules you must follow:
-- Do not output any explanations or additional text.
-- The categories must be from the allowed list.
-- The categories must be relevant to the API's functionality and purpose.
-- The categories should be in a comma-separated format.
-- If you cannot determine appropriate categories, respond with 'None'.
+- Only return categories from the allowed list.
+- Choose categories relevant to the API's core functionality.
+- Return a comma-separated list of categories, no more than 3.
+- If no appropriate category can be confidently determined, return `None`.
+- Do not include explanations or additional text.
 
 Example:
-Server URL: https://api.example.com
-Response: Data
+Server URL: https://api.example.com  
+API Description: A service that provides document collaboration features  
+Operation Descriptions:
+- Share a document with another user.  
+- Retrieve a list of collaborators.  
+- Update document permissions.  
+Response: Collaboration, Content and Files
 
 user:
-Server URL: {{serverUrl}}
+Server URL: {{serverUrl}}  
+API Description: {{apiDescription}}  
+Operation Descriptions:
+{{operationDescriptions}}
+Response: