Skip to content

Commit

Permalink
.Net: Rename OpenAPI model classes (#9595)
Browse files Browse the repository at this point in the history 
### 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.
  • Loading branch information
@SergeyMenshykh
SergeyMenshykh authored Nov 7, 2024
1 parent 3888c8e commit daafde4
Show file tree
Hide file tree
Showing 31 changed files with 460 additions and 458 deletions.
20 changes: 10 additions & 10 deletions dotnet/src/Functions/Functions.OpenApi/Extensions/OpenApiFunctionExecutionParameters.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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; }
Expand All @@ -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; }

Expand Down Expand Up @@ -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>
Expand Down
48 changes: 24 additions & 24 deletions dotnet/src/Functions/Functions.OpenApi/Extensions/RestApiOperationExtensions.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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;
Expand All @@ -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)
{
Expand All @@ -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)
{
Expand Down Expand Up @@ -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.");
}

Expand All @@ -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,
Expand All @@ -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)
{
Expand Down
2 changes: 1 addition & 1 deletion dotnet/src/Functions/Functions.OpenApi/HttpContentFactory.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
8 changes: 4 additions & 4 deletions ...Model/RestApiOperationExpectedResponse.cs → ....OpenApi/Model/RestApiExpectedResponse.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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;
Expand Down
40 changes: 21 additions & 19 deletions dotnet/src/Functions/Functions.OpenApi/Model/RestApiOperation.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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;
Expand All @@ -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>
Expand Down Expand Up @@ -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)
{
Expand All @@ -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))
{
Expand All @@ -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)
{
Expand All @@ -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))
{
Expand All @@ -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)
{
Expand All @@ -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))
{
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit daafde4

Please sign in to comment.