.Net: Rename OpenAPI model classes (#9595)

### Motivation, Context and Description
The public OpenAPI model classes that have "operation" in their name
were renamed to align with the other classes that do not have the word
in their name.
Additionally, the `RestApiPayloadProperty.Type`,
`RestApiParameter.Type`, and `RestApiParameter.ArrayItemType` were made
internal to simplify the update to OpenAPI.NET v2, where their types
have been changed.

Author: SergeyMenshykh

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

@@ -23,13 +23,13 @@ public class OpenApiFunctionExecutionParameters
     public AuthenticateRequestAsyncCallback? AuthCallback { get; set; }
 
     /// <summary>
-    /// Override for REST API operation server url.
+    /// Override for REST API server url.
     /// </summary>
     public Uri? ServerUrlOverride { get; set; }
 
     /// <summary>
-    /// Flag indicating whether to ignore non-compliant errors or not.
-    /// If set to true, the operation execution will not throw exceptions for non-compliant documents.
+    /// Flag indicating whether to ignore non-compliant errors of the OpenAPI document or not.
+    /// If set to true, the execution will not throw exceptions for non-compliant documents.
     /// Please note that enabling this option may result in incomplete or inaccurate execution results.
     /// </summary>
     public bool IgnoreNonCompliantErrors { get; set; }
@@ -40,8 +40,8 @@ public class OpenApiFunctionExecutionParameters
     public string UserAgent { get; set; }
 
     /// <summary>
-    /// Determines whether the operation payload is constructed dynamically based on operation payload metadata.
-    /// If false, the operation payload must be provided via the 'payload' context variable.
+    /// Determines whether the REST API operation payload is constructed dynamically based on payload metadata.
+    /// If false, the payload must be provided via the 'payload' argument.
     /// </summary>
     public bool EnableDynamicPayload { get; set; }
 
@@ -75,13 +75,13 @@ public class OpenApiFunctionExecutionParameters
     /// </summary>
     /// <param name="httpClient">The HttpClient to use for sending HTTP requests.</param>
     /// <param name="authCallback">The callback for adding authentication data to HTTP requests.</param>
-    /// <param name="serverUrlOverride">The override for the REST API operation server URL.</param>
+    /// <param name="serverUrlOverride">The override for the REST API server URL.</param>
     /// <param name="userAgent">Optional user agent header value.</param>
-    /// <param name="ignoreNonCompliantErrors">A flag indicating whether to ignore non-compliant errors or not
-    /// If set to true, the operation execution will not throw exceptions for non-compliant documents.
+    /// <param name="ignoreNonCompliantErrors">A flag indicating whether to ignore non-compliant errors of the OpenAPI document or not
+    /// If set to true, the execution will not throw exceptions for non-compliant documents.
     /// Please note that enabling this option may result in incomplete or inaccurate execution results.</param>
-    /// <param name="enableDynamicOperationPayload">Determines whether the operation payload is constructed dynamically based on operation payload metadata.
-    /// If false, the operation payload must be provided via the 'payload' context variable.</param>
+    /// <param name="enableDynamicOperationPayload">Determines whether the REST API operation payload is constructed dynamically based on payload metadata.
+    /// If false, the REST API payload must be provided via the 'payload' argument.</param>
     /// <param name="enablePayloadNamespacing">Determines whether payload parameter names are augmented with namespaces.
     /// Namespaces prevent naming conflicts by adding the parent parameter name as a prefix, separated by dots.</param>
     /// <param name="operationsToExclude">Optional list of operations not to import, e.g. in case they are not supported</param>

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

@@ -25,12 +25,12 @@ internal static partial class RestApiOperationExtensions
     /// the parameters 'sender.email' and 'receiver.mail' will be correctly resolved from arguments with the same names.
     /// </param>
     /// <returns>The list of parameters.</returns>
-    public static IReadOnlyList<RestApiOperationParameter> GetParameters(
+    public static IReadOnlyList<RestApiParameter> GetParameters(
         this RestApiOperation operation,
         bool addPayloadParamsFromMetadata = true,
         bool enablePayloadNamespacing = false)
     {
-        var parameters = new List<RestApiOperationParameter>(operation.Parameters);
+        var parameters = new List<RestApiParameter>(operation.Parameters);
 
         // Add payload parameters
         if (operation.Payload is not null)
@@ -55,7 +55,7 @@ public static IReadOnlyList<RestApiOperationParameter> GetParameters(
     /// <returns>The default return parameter metadata, if any.</returns>
     public static KernelReturnParameterMetadata? GetDefaultReturnParameter(this RestApiOperation operation, string[]? preferredResponses = null)
     {
-        RestApiOperationExpectedResponse? restOperationResponse = GetDefaultResponse(operation.Responses, preferredResponses ??= s_preferredResponses);
+        RestApiExpectedResponse? restOperationResponse = GetDefaultResponse(operation.Responses, preferredResponses ??= s_preferredResponses);
 
         var returnParameter =
             restOperationResponse is not null ? new KernelReturnParameterMetadata { Description = restOperationResponse.Description, Schema = restOperationResponse.Schema } : null;
@@ -64,12 +64,12 @@ public static IReadOnlyList<RestApiOperationParameter> GetParameters(
     }
 
     /// <summary>
-    /// Retrieves the default response for a given REST API operation.
+    /// Retrieves the default response.
     /// </summary>
-    /// <param name="responses">The REST API operation responses to parse.</param>
+    /// <param name="responses">Possible REST API responses.</param>
     /// <param name="preferredResponses">The preferred response codes to use when selecting the default response.</param>
     /// <returns>The default response, if any.</returns>
-    private static RestApiOperationExpectedResponse? GetDefaultResponse(IReadOnlyDictionary<string, RestApiOperationExpectedResponse> responses, string[] preferredResponses)
+    private static RestApiExpectedResponse? GetDefaultResponse(IReadOnlyDictionary<string, RestApiExpectedResponse> responses, string[] preferredResponses)
     {
         foreach (var code in preferredResponses)
         {
@@ -90,8 +90,8 @@ public static IReadOnlyList<RestApiOperationParameter> GetParameters(
     /// <param name="useParametersFromMetadata">Flag indicating whether to include parameters from metadata.
     /// If false or not specified, the 'payload' and 'content-type' parameters are added instead.</param>
     /// <param name="enableNamespacing">Flag indicating whether to namespace payload parameter names.</param>
-    /// <returns>A list of <see cref="RestApiOperationParameter"/> representing the payload parameters.</returns>
-    private static List<RestApiOperationParameter> GetPayloadParameters(RestApiOperation operation, bool useParametersFromMetadata, bool enableNamespacing)
+    /// <returns>A list of <see cref="RestApiParameter"/> representing the payload parameters.</returns>
+    private static List<RestApiParameter> GetPayloadParameters(RestApiOperation operation, bool useParametersFromMetadata, bool enableNamespacing)
     {
         if (useParametersFromMetadata)
         {
@@ -122,15 +122,15 @@ private static List<RestApiOperationParameter> GetPayloadParameters(RestApiOpera
     /// </summary>
     /// <param name="operation">The REST API operation.</param>
     /// <returns>The 'content-type' artificial parameter.</returns>
-    private static RestApiOperationParameter CreateContentTypeArtificialParameter(RestApiOperation operation)
+    private static RestApiParameter CreateContentTypeArtificialParameter(RestApiOperation operation)
     {
-        return new RestApiOperationParameter(
+        return new RestApiParameter(
             RestApiOperation.ContentTypeArgumentName,
             "string",
             isRequired: false,
             expand: false,
-            RestApiOperationParameterLocation.Body,
-            RestApiOperationParameterStyle.Simple,
+            RestApiParameterLocation.Body,
+            RestApiParameterStyle.Simple,
             description: "Content type of REST API request body.");
     }
 
@@ -139,45 +139,45 @@ private static RestApiOperationParameter CreateContentTypeArtificialParameter(Re
     /// </summary>
     /// <param name="operation">The REST API operation.</param>
     /// <returns>The 'payload' artificial parameter.</returns>
-    private static RestApiOperationParameter CreatePayloadArtificialParameter(RestApiOperation operation)
+    private static RestApiParameter CreatePayloadArtificialParameter(RestApiOperation operation)
     {
-        return new RestApiOperationParameter(
+        return new RestApiParameter(
             RestApiOperation.PayloadArgumentName,
             operation.Payload?.MediaType == MediaTypeTextPlain ? "string" : "object",
             isRequired: true,
             expand: false,
-            RestApiOperationParameterLocation.Body,
-            RestApiOperationParameterStyle.Simple,
+            RestApiParameterLocation.Body,
+            RestApiParameterStyle.Simple,
             description: operation.Payload?.Description ?? "REST API request body.",
             schema: operation.Payload?.Schema);
     }
 
     /// <summary>
-    /// Retrieves parameters from REST API operation payload metadata.
+    /// Retrieves parameters from REST API payload metadata.
     /// </summary>
-    /// <param name="properties">The REST API operation payload properties.</param>
+    /// <param name="properties">The REST API payload properties.</param>
     /// <param name="enableNamespacing">Determines whether property names are augmented with namespaces.
     /// Namespaces are created by prefixing property names with their root property names.
     /// </param>
     /// <param name="rootPropertyName">The root property name.</param>
     /// <returns>The list of payload parameters.</returns>
-    private static List<RestApiOperationParameter> GetParametersFromPayloadMetadata(IReadOnlyList<RestApiOperationPayloadProperty> properties, bool enableNamespacing = false, string? rootPropertyName = null)
+    private static List<RestApiParameter> GetParametersFromPayloadMetadata(IReadOnlyList<RestApiPayloadProperty> properties, bool enableNamespacing = false, string? rootPropertyName = null)
     {
-        var parameters = new List<RestApiOperationParameter>();
+        var parameters = new List<RestApiParameter>();
 
         foreach (var property in properties)
         {
             var parameterName = GetPropertyName(property, rootPropertyName, enableNamespacing);
 
             if (!property.Properties.Any())
             {
-                parameters.Add(new RestApiOperationParameter(
+                parameters.Add(new RestApiParameter(
                     name: parameterName,
                     type: property.Type,
                     isRequired: property.IsRequired,
                     expand: false,
-                    location: RestApiOperationParameterLocation.Body,
-                    style: RestApiOperationParameterStyle.Simple,
+                    location: RestApiParameterLocation.Body,
+                    style: RestApiParameterStyle.Simple,
                     defaultValue: property.DefaultValue,
                     description: property.Description,
                     format: property.Format,
@@ -197,7 +197,7 @@ private static List<RestApiOperationParameter> GetParametersFromPayloadMetadata(
     /// <param name="rootPropertyName">The root property name to be used for constructing the full property name.</param>
     /// <param name="enableNamespacing">Determines whether to add namespace to property name or not.</param>
     /// <returns>The property name.</returns>
-    private static string GetPropertyName(RestApiOperationPayloadProperty property, string? rootPropertyName, bool enableNamespacing = false)
+    private static string GetPropertyName(RestApiPayloadProperty property, string? rootPropertyName, bool enableNamespacing = false)
     {
         if (enableNamespacing)
         {

dotnet/src/Functions/Functions.OpenApi/HttpContentFactory.cs

@@ -11,4 +11,4 @@ namespace Microsoft.SemanticKernel.Plugins.OpenApi;
 /// <param name="payload">The operation payload metadata.</param>
 /// <param name="arguments">The operation arguments.</param>
 /// <returns>The object and HttpContent representing the operation payload.</returns>
-internal delegate (object? Payload, HttpContent Content) HttpContentFactory(RestApiOperationPayload? payload, IDictionary<string, object?> arguments);
+internal delegate (object? Payload, HttpContent Content) HttpContentFactory(RestApiPayload? payload, IDictionary<string, object?> arguments);

dotnet/src/Functions/Functions.OpenApi/Model/RestApiOperationExpectedResponse.cs renamed to dotnet/src/Functions/Functions.OpenApi/Model/RestApiExpectedResponse.cs

@@ -5,10 +5,10 @@
 namespace Microsoft.SemanticKernel.Plugins.OpenApi;
 
 /// <summary>
-/// The REST API operation response.
+/// REST API response.
 /// </summary>
 [Experimental("SKEXP0040")]
-public sealed class RestApiOperationExpectedResponse
+public sealed class RestApiExpectedResponse
 {
     /// <summary>
     /// Gets the description of the response.
@@ -26,12 +26,12 @@ public sealed class RestApiOperationExpectedResponse
     public KernelJsonSchema? Schema { get; }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="RestApiOperationResponse"/> class.
+    /// Initializes a new instance of the <see cref="RestApiExpectedResponse"/> class.
     /// </summary>
     /// <param name="description">The description of the response.</param>
     /// <param name="mediaType">The media type of the response.</param>
     /// <param name="schema">The schema against which the response body should be validated.</param>
-    internal RestApiOperationExpectedResponse(string description, string mediaType, KernelJsonSchema? schema = null)
+    internal RestApiExpectedResponse(string description, string mediaType, KernelJsonSchema? schema = null)
     {
         this.Description = description;
         this.MediaType = mediaType;

dotnet/src/Functions/Functions.OpenApi/Model/RestApiOperation.cs

@@ -54,7 +54,7 @@ public sealed class RestApiOperation
     /// <summary>
     /// The server.
     /// </summary>
-    public IReadOnlyList<RestApiOperationServer> Servers { get; }
+    public IReadOnlyList<RestApiServer> Servers { get; }
 
     /// <summary>
     /// The security requirements.
@@ -64,17 +64,17 @@ public sealed class RestApiOperation
     /// <summary>
     /// The operation parameters.
     /// </summary>
-    public IReadOnlyList<RestApiOperationParameter> Parameters { get; }
+    public IReadOnlyList<RestApiParameter> Parameters { get; }
 
     /// <summary>
     /// The list of possible operation responses.
     /// </summary>
-    public IReadOnlyDictionary<string, RestApiOperationExpectedResponse> Responses { get; }
+    public IReadOnlyDictionary<string, RestApiExpectedResponse> Responses { get; }
 
     /// <summary>
     /// The operation payload.
     /// </summary>
-    public RestApiOperationPayload? Payload { get; }
+    public RestApiPayload? Payload { get; }
 
     /// <summary>
     /// Additional unstructured metadata about the operation.
@@ -95,14 +95,14 @@ public sealed class RestApiOperation
     /// <param name="payload">The operation payload.</param>
     internal RestApiOperation(
         string? id,
-        IReadOnlyList<RestApiOperationServer> servers,
+        IReadOnlyList<RestApiServer> servers,
         string path,
         HttpMethod method,
         string? description,
-        IReadOnlyList<RestApiOperationParameter> parameters,
-        IReadOnlyDictionary<string, RestApiOperationExpectedResponse> responses,
+        IReadOnlyList<RestApiParameter> parameters,
+        IReadOnlyDictionary<string, RestApiExpectedResponse> responses,
         IReadOnlyList<RestApiSecurityRequirement> securityRequirements,
-        RestApiOperationPayload? payload = null)
+        RestApiPayload? payload = null)
     {
         this.Id = id;
         this.Servers = servers;
@@ -113,6 +113,8 @@ internal RestApiOperation(
         this.Responses = responses;
         this.SecurityRequirements = securityRequirements;
         this.Payload = payload;
+        this.Responses = responses ?? new Dictionary<string, RestApiExpectedResponse>();
+        this.SecurityRequirements = securityRequirements;
     }
 
     /// <summary>
@@ -140,7 +142,7 @@ internal IDictionary<string, string> BuildHeaders(IDictionary<string, object?> a
     {
         var headers = new Dictionary<string, string>();
 
-        var parameters = this.Parameters.Where(p => p.Location == RestApiOperationParameterLocation.Header);
+        var parameters = this.Parameters.Where(p => p.Location == RestApiParameterLocation.Header);
 
         foreach (var parameter in parameters)
         {
@@ -156,7 +158,7 @@ internal IDictionary<string, string> BuildHeaders(IDictionary<string, object?> a
                 continue;
             }
 
-            var parameterStyle = parameter.Style ?? RestApiOperationParameterStyle.Simple;
+            var parameterStyle = parameter.Style ?? RestApiParameterStyle.Simple;
 
             if (!s_parameterSerializers.TryGetValue(parameterStyle, out var serializer))
             {
@@ -181,7 +183,7 @@ internal string BuildQueryString(IDictionary<string, object?> arguments)
     {
         var segments = new List<string>();
 
-        var parameters = this.Parameters.Where(p => p.Location == RestApiOperationParameterLocation.Query);
+        var parameters = this.Parameters.Where(p => p.Location == RestApiParameterLocation.Query);
 
         foreach (var parameter in parameters)
         {
@@ -197,7 +199,7 @@ internal string BuildQueryString(IDictionary<string, object?> arguments)
                 continue;
             }
 
-            var parameterStyle = parameter.Style ?? RestApiOperationParameterStyle.Form;
+            var parameterStyle = parameter.Style ?? RestApiParameterStyle.Form;
 
             if (!s_parameterSerializers.TryGetValue(parameterStyle, out var serializer))
             {
@@ -223,7 +225,7 @@ internal string BuildQueryString(IDictionary<string, object?> arguments)
     /// <returns>The path.</returns>
     private string BuildPath(string pathTemplate, IDictionary<string, object?> arguments)
     {
-        var parameters = this.Parameters.Where(p => p.Location == RestApiOperationParameterLocation.Path);
+        var parameters = this.Parameters.Where(p => p.Location == RestApiParameterLocation.Path);
 
         foreach (var parameter in parameters)
         {
@@ -239,7 +241,7 @@ private string BuildPath(string pathTemplate, IDictionary<string, object?> argum
                 continue;
             }
 
-            var parameterStyle = parameter.Style ?? RestApiOperationParameterStyle.Simple;
+            var parameterStyle = parameter.Style ?? RestApiParameterStyle.Simple;
 
             if (!s_parameterSerializers.TryGetValue(parameterStyle, out var serializer))
             {
@@ -307,12 +309,12 @@ private Uri GetServerUrl(Uri? serverUrlOverride, Uri? apiHostUrl, IDictionary<st
         return new Uri(serverUrlString);
     }
 
-    private static readonly Dictionary<RestApiOperationParameterStyle, Func<RestApiOperationParameter, JsonNode, string>> s_parameterSerializers = new()
+    private static readonly Dictionary<RestApiParameterStyle, Func<RestApiParameter, JsonNode, string>> s_parameterSerializers = new()
     {
-        { RestApiOperationParameterStyle.Simple, SimpleStyleParameterSerializer.Serialize },
-        { RestApiOperationParameterStyle.Form, FormStyleParameterSerializer.Serialize },
-        { RestApiOperationParameterStyle.SpaceDelimited, SpaceDelimitedStyleParameterSerializer.Serialize },
-        { RestApiOperationParameterStyle.PipeDelimited, PipeDelimitedStyleParameterSerializer.Serialize }
+        { RestApiParameterStyle.Simple, SimpleStyleParameterSerializer.Serialize },
+        { RestApiParameterStyle.Form, FormStyleParameterSerializer.Serialize },
+        { RestApiParameterStyle.SpaceDelimited, SpaceDelimitedStyleParameterSerializer.Serialize },
+        { RestApiParameterStyle.PipeDelimited, PipeDelimitedStyleParameterSerializer.Serialize }
     };
 
     # endregion