.Net: revise public api surface of the rest-api model (#9549)

### Motivation and Context
Taking into account the plans to add REST API operation details to
KernelFunction.Metadata, it makes sense to review the REST API operation
model classes and ensure their surface is good enough to be publicly
exposed, making it easy for the SK team to develop them over time with
minimal or no breaking changes.

### Description  
1. Changes collections/dictionaries to their read-only equivalents to
prevent modifications - metadata is read-only.
2. Makes the constructors of REST API operation model classes internal,
allowing changes and development without the concern of introducing
breaking changes.

Closes: #6884

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

@@ -69,7 +69,7 @@ public static IReadOnlyList<RestApiOperationParameter> GetParameters(
     /// <param name="responses">The REST API operation responses to parse.</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(IDictionary<string, RestApiOperationExpectedResponse> responses, string[] preferredResponses)
+    private static RestApiOperationExpectedResponse? GetDefaultResponse(IReadOnlyDictionary<string, RestApiOperationExpectedResponse> responses, string[] preferredResponses)
     {
         foreach (var code in preferredResponses)
         {
@@ -161,7 +161,7 @@ private static RestApiOperationParameter CreatePayloadArtificialParameter(RestAp
     /// </param>
     /// <param name="rootPropertyName">The root property name.</param>
     /// <returns>The list of payload parameters.</returns>
-    private static List<RestApiOperationParameter> GetParametersFromPayloadMetadata(IList<RestApiOperationPayloadProperty> properties, bool enableNamespacing = false, string? rootPropertyName = null)
+    private static List<RestApiOperationParameter> GetParametersFromPayloadMetadata(IReadOnlyList<RestApiOperationPayloadProperty> properties, bool enableNamespacing = false, string? rootPropertyName = null)
     {
         var parameters = new List<RestApiOperationParameter>();
 

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

@@ -5,7 +5,7 @@ namespace Microsoft.SemanticKernel.Plugins.OpenApi;
 /// <summary>
 /// The REST API information.
 /// </summary>
-internal sealed class RestApiInfo
+public sealed class RestApiInfo
 {
     /// <summary>
     /// The title of the application.
@@ -21,4 +21,11 @@ internal sealed class RestApiInfo
     /// The version of the OpenAPI document.
     /// </summary>
     public string? Version { get; init; }
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="RestApiInfo"/> class.
+    /// </summary>
+    internal RestApiInfo()
+    {
+    }
 }

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

@@ -57,12 +57,12 @@ public sealed class RestApiOperation
     /// <summary>
     /// The operation parameters.
     /// </summary>
-    public IList<RestApiOperationParameter> Parameters { get; }
+    public IReadOnlyList<RestApiOperationParameter> Parameters { get; }
 
     /// <summary>
     /// The list of possible operation responses.
     /// </summary>
-    public IDictionary<string, RestApiOperationExpectedResponse> Responses { get; }
+    public IReadOnlyDictionary<string, RestApiOperationExpectedResponse> Responses { get; }
 
     /// <summary>
     /// The operation payload.
@@ -85,15 +85,15 @@ public sealed class RestApiOperation
     /// <param name="parameters">The operation parameters.</param>
     /// <param name="payload">The operation payload.</param>
     /// <param name="responses">The operation responses.</param>
-    public RestApiOperation(
+    internal RestApiOperation(
         string id,
         RestApiOperationServer server,
         string path,
         HttpMethod method,
         string description,
-        IList<RestApiOperationParameter> parameters,
+        IReadOnlyList<RestApiOperationParameter> parameters,
         RestApiOperationPayload? payload = null,
-        IDictionary<string, RestApiOperationExpectedResponse>? responses = null)
+        IReadOnlyDictionary<string, RestApiOperationExpectedResponse>? responses = null)
     {
         this.Id = id;
         this.Server = server;
@@ -112,7 +112,7 @@ public RestApiOperation(
     /// <param name="serverUrlOverride">Override for REST API operation server url.</param>
     /// <param name="apiHostUrl">The URL of REST API host.</param>
     /// <returns>The operation Url.</returns>
-    public Uri BuildOperationUrl(IDictionary<string, object?> arguments, Uri? serverUrlOverride = null, Uri? apiHostUrl = null)
+    internal Uri BuildOperationUrl(IDictionary<string, object?> arguments, Uri? serverUrlOverride = null, Uri? apiHostUrl = null)
     {
         var serverUrl = this.GetServerUrl(serverUrlOverride, apiHostUrl, arguments);
 
@@ -126,7 +126,7 @@ public Uri BuildOperationUrl(IDictionary<string, object?> arguments, Uri? server
     /// </summary>
     /// <param name="arguments">The operation arguments.</param>
     /// <returns>The request headers.</returns>
-    public IDictionary<string, string> BuildHeaders(IDictionary<string, object?> arguments)
+    internal IDictionary<string, string> BuildHeaders(IDictionary<string, object?> arguments)
     {
         var headers = new Dictionary<string, string>();
 
@@ -167,7 +167,7 @@ public IDictionary<string, string> BuildHeaders(IDictionary<string, object?> arg
     /// </summary>
     /// <param name="arguments">The operation arguments.</param>
     /// <returns>The query string.</returns>
-    public string BuildQueryString(IDictionary<string, object?> arguments)
+    internal string BuildQueryString(IDictionary<string, object?> arguments)
     {
         var segments = new List<string>();
 

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

@@ -20,15 +20,15 @@ public sealed class RestApiOperationExpectedResponse
     /// <summary>
     /// The schema of the response.
     /// </summary>
-    public KernelJsonSchema? Schema { get; set; }
+    public KernelJsonSchema? Schema { get; }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="RestApiOperationResponse"/> 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>
-    public RestApiOperationExpectedResponse(string description, string mediaType, KernelJsonSchema? schema = null)
+    internal RestApiOperationExpectedResponse(string description, string mediaType, KernelJsonSchema? schema = null)
     {
         this.Description = description;
         this.MediaType = mediaType;

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

@@ -15,7 +15,7 @@ public sealed class RestApiOperationParameter
     /// <summary>
     /// The property alternative name. It can be used as an alternative name in contexts where the original name can't be used.
     /// </summary>
-    public string? AlternativeName { get; set; }
+    public string? AlternativeName { get; internal set; }
 
     /// <summary>
     /// The parameter type - string, integer, number, boolean, array and object.
@@ -83,7 +83,7 @@ public sealed class RestApiOperationParameter
     /// <param name="format">The parameter type modifier that refines the generic parameter type to a more specific one.
     /// More details can be found at https://swagger.io/docs/specification/data-models/data-types</param>
     /// <param name="schema">The parameter schema.</param>
-    public RestApiOperationParameter(
+    internal RestApiOperationParameter(
         string name,
         string type,
         bool isRequired,

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

@@ -7,7 +7,7 @@ namespace Microsoft.SemanticKernel.Plugins.OpenApi;
 /// <summary>
 /// The REST API operation payload.
 /// </summary>
-public class RestApiOperationPayload
+public sealed class RestApiOperationPayload
 {
     /// <summary>
     /// The payload MediaType.
@@ -22,7 +22,7 @@ public class RestApiOperationPayload
     /// <summary>
     /// The payload properties.
     /// </summary>
-    public IList<RestApiOperationPayloadProperty> Properties { get; }
+    public IReadOnlyList<RestApiOperationPayloadProperty> Properties { get; }
 
     /// <summary>
     /// The schema of the parameter.
@@ -36,7 +36,7 @@ public class RestApiOperationPayload
     /// <param name="properties">The properties.</param>
     /// <param name="description">The description.</param>
     /// <param name="schema">The JSON Schema.</param>
-    public RestApiOperationPayload(string mediaType, IList<RestApiOperationPayloadProperty> properties, string? description = null, KernelJsonSchema? schema = null)
+    internal RestApiOperationPayload(string mediaType, IReadOnlyList<RestApiOperationPayloadProperty> properties, string? description = null, KernelJsonSchema? schema = null)
     {
         this.MediaType = mediaType;
         this.Properties = properties;

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

@@ -38,7 +38,7 @@ public sealed class RestApiOperationPayloadProperty
     /// <summary>
     /// The properties.
     /// </summary>
-    public IList<RestApiOperationPayloadProperty> Properties { get; }
+    public IReadOnlyList<RestApiOperationPayloadProperty> Properties { get; }
 
     /// <summary>
     /// The schema of the parameter.
@@ -63,11 +63,11 @@ public sealed class RestApiOperationPayloadProperty
     /// <param name="schema">The schema of the payload property.</param>
     /// <param name="defaultValue">The default value of the property.</param>
     /// <returns>Returns a new instance of the <see cref="RestApiOperationPayloadProperty"/> class.</returns>
-    public RestApiOperationPayloadProperty(
+    internal RestApiOperationPayloadProperty(
         string name,
         string type,
         bool isRequired,
-        IList<RestApiOperationPayloadProperty> properties,
+        IReadOnlyList<RestApiOperationPayloadProperty> properties,
         string? description = null,
         string? format = null,
         KernelJsonSchema? schema = null,

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

@@ -29,7 +29,7 @@ public sealed class RestApiOperationServer
     /// <param name="url">URL to the target host</param>
     /// <param name="variables">Substitution variables for the server's URL template</param>
 #pragma warning disable CA1054 // URI-like parameters should not be strings
-    public RestApiOperationServer(string? url = null, IDictionary<string, RestApiOperationServerVariable>? variables = null)
+    internal RestApiOperationServer(string? url = null, IDictionary<string, RestApiOperationServerVariable>? variables = null)
 #pragma warning restore CA1054 // URI-like parameters should not be strings
     {
         this.Url = string.IsNullOrEmpty(url) ? null : url;

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.Collections.Generic;
+using System.Linq;
 
 namespace Microsoft.SemanticKernel.Plugins.OpenApi;
 
@@ -23,15 +24,15 @@ public sealed class RestApiOperationServerVariable
     /// <summary>
     /// An enumeration of string values to be used if the substitution options are from a limited set.
     /// </summary>
-    public List<string>? Enum { get; }
+    public IReadOnlyList<string>? Enum { get; }
 
     /// <summary>
     /// Construct a new <see cref="RestApiOperationServerVariable"/> object.
     /// </summary>
     /// <param name="defaultValue">The default value to use for substitution.</param>
     /// <param name="description">An optional description for the server variable.</param>
     /// <param name="enumValues">An enumeration of string values to be used if the substitution options are from a limited set.</param>
-    public RestApiOperationServerVariable(string defaultValue, string? description = null, List<string>? enumValues = null)
+    internal RestApiOperationServerVariable(string defaultValue, string? description = null, List<string>? enumValues = null)
     {
         this.Default = defaultValue;
         this.Description = description;

dotnet/src/Functions/Functions.OpenApi/RestApiOperationRunner.cs

@@ -374,7 +374,7 @@ private async Task<RestApiOperationResponse> ReadContentAndCreateOperationRespon
     /// <param name="arguments">The arguments.</param>
     /// <param name="propertyNamespace">The namespace to add to the property name.</param>
     /// <returns>The JSON object.</returns>
-    private JsonObject BuildJsonObject(IList<RestApiOperationPayloadProperty> properties, IDictionary<string, object?> arguments, string? propertyNamespace = null)
+    private JsonObject BuildJsonObject(IReadOnlyList<RestApiOperationPayloadProperty> properties, IDictionary<string, object?> arguments, string? propertyNamespace = null)
     {
         var result = new JsonObject();