/// <summary>
/// Returns a value indicating whether the provided action maps to the specified API version.
/// </summary>
/// <param name="action">The <see cref="HttpActionDescriptor">action</see> to evaluate.</param>
/// <param name="apiVersion">The <see cref="ApiVersion">API version</see> to test the mapping for.</param>
/// <returns>One of the <see cref="ApiVersionMapping"/> values.</returns>
public static ApiVersionMapping MappingTo(this HttpActionDescriptor action, ApiVersion?apiVersion)
{
if (action == null)
{
throw new ArgumentNullException(nameof(action));
}
var model = action.GetApiVersionModel();
if (model.IsApiVersionNeutral || (apiVersion != null && model.DeclaredApiVersions.Contains(apiVersion)))
{
return(Explicit);
}
else if (model.DeclaredApiVersions.Count == 0)
{
model = action.ControllerDescriptor.GetApiVersionModel();
if (apiVersion != null && model.DeclaredApiVersions.Contains(apiVersion))
{
return(Implicit);
}
}
return(None);
}
void PopulateActionDescriptions(
HttpActionDescriptor actionDescriptor,
IHttpRoute route,
ODataRouteBuilderContext routeBuilderContext,
string relativePath,
Collection <VersionedApiDescription> apiDescriptions,
ApiVersion apiVersion)
{
Contract.Requires(actionDescriptor != null);
Contract.Requires(route != null);
Contract.Requires(relativePath != null);
Contract.Requires(apiDescriptions != null);
Contract.Requires(apiVersion != null);
var documentation = DocumentationProvider?.GetDocumentation(actionDescriptor);
var responseDescription = CreateResponseDescriptionWithRoute(actionDescriptor, route);
var responseType = responseDescription.ResponseType ?? responseDescription.DeclaredType;
var requestFormatters = new List <MediaTypeFormatter>();
var responseFormatters = new List <MediaTypeFormatter>();
var supportedMethods = GetHttpMethodsSupportedByAction(route, actionDescriptor);
var model = actionDescriptor.GetApiVersionModel();
var deprecated = !model.IsApiVersionNeutral && model.DeprecatedApiVersions.Contains(apiVersion);
PopulateMediaTypeFormatters(actionDescriptor, routeBuilderContext.ParameterDescriptions, route, responseType, requestFormatters, responseFormatters);
foreach (var method in supportedMethods)
{
var apiDescription = new VersionedApiDescription()
{
Documentation = documentation,
HttpMethod = method,
RelativePath = relativePath,
ActionDescriptor = actionDescriptor,
Route = route,
ResponseDescription = responseDescription,
ApiVersion = apiVersion,
IsDeprecated = deprecated,
Properties = { [typeof(IEdmModel)] = routeBuilderContext.EdmModel },
};
if (routeBuilderContext.EntitySet != null)
{
apiDescription.Properties[typeof(IEdmEntitySet)] = routeBuilderContext.EntitySet;
}
if (routeBuilderContext.Operation != null)
{
apiDescription.Properties[typeof(IEdmOperation)] = routeBuilderContext.Operation;
}
apiDescription.ParameterDescriptions.AddRange(routeBuilderContext.ParameterDescriptions);
apiDescription.SupportedRequestBodyFormatters.AddRange(requestFormatters);
apiDescription.SupportedResponseFormatters.AddRange(responseFormatters);
PopulateApiVersionParameters(apiDescription, apiVersion);
apiDescriptions.Add(apiDescription);
}
}
public void get_api_versions_should_return_expected_action_descriptor_results(HttpActionDescriptor actionDescriptor, IEnumerable <ApiVersion> expectedVersions)
{
// arrange
// act
var declaredVersions = actionDescriptor.GetApiVersionModel().DeclaredApiVersions;
// assert
declaredVersions.Should().BeEquivalentTo(expectedVersions);
}
/// <summary>
/// Returns a value indicating whether the specified action should be mapped using attribute routing conventions.
/// </summary>
/// <param name="action">The <see cref="HttpActionDescriptor">action descriptor</see> to evaluate.</param>
/// <returns>True if the <paramref name="action"/> should be mapped as an OData action or function; otherwise, false.</returns>
/// <remarks>This method will match any OData action that explicitly or implicitly matches matches the API version applied
/// to the associated <see cref="ApiVersionModel">model</see>.</remarks>
public virtual bool ShouldMapAction(HttpActionDescriptor action)
{
Arg.NotNull(action, nameof(action));
var model = action.GetApiVersionModel();
if (model.IsApiVersionNeutral)
{
return(true);
}
else if (model.DeclaredApiVersions.Count == 0)
{
return(ShouldMapController(action.ControllerDescriptor));
}
return(model.DeclaredApiVersions.Contains(ApiVersion));
}
/// <summary>
/// Returns a value indicating whether the provided action maps to the specified API version.
/// </summary>
/// <param name="action">The <see cref="HttpActionDescriptor">action</see> to evaluate.</param>
/// <param name="apiVersion">The <see cref="ApiVersion">API version</see> to test the mapping for.</param>
/// <returns>One of the <see cref="ApiVersionMapping"/> values.</returns>
public static ApiVersionMapping MappingTo(this HttpActionDescriptor action, ApiVersion?apiVersion)
{
if (action == null)
{
throw new ArgumentNullException(nameof(action));
}
var model = action.GetApiVersionModel();
if (model.IsApiVersionNeutral)
{
return(Explicit);
}
if (apiVersion is null)
{
return(None);
}
var mappedWithImplementation = model.DeclaredApiVersions.Contains(apiVersion) &&
model.ImplementedApiVersions.Contains(apiVersion);
if (mappedWithImplementation)
{
return(Explicit);
}
var deriveFromParent = model.DeclaredApiVersions.Count == 0;
if (deriveFromParent)
{
model = action.ControllerDescriptor.GetApiVersionModel();
if (model.DeclaredApiVersions.Contains(apiVersion))
{
return(Implicit);
}
}
return(None);
}
/// <summary>
/// Returns a value indicating whether the provided action maps to the specified API version.
/// </summary>
/// <param name="action">The <see cref="HttpActionDescriptor">action</see> to evaluate.</param>
/// <param name="apiVersion">The <see cref="ApiVersion">API version</see> to test the mapping for.</param>
/// <returns>One of the <see cref="ApiVersionMapping"/> values.</returns>
public static ApiVersionMapping MappingTo(this HttpActionDescriptor action, ApiVersion apiVersion)
{
Arg.NotNull(action, nameof(action));
var model = action.GetApiVersionModel();
if (model.IsApiVersionNeutral || (apiVersion != null && model.DeclaredApiVersions.Contains(apiVersion)))
{
return(Explicit);
}
else if (model.DeclaredApiVersions.Count == 0)
{
model = action.ControllerDescriptor.GetApiVersionModel();
if (apiVersion != null && model.DeclaredApiVersions.Contains(apiVersion))
{
return(Implicit);
}
}
return(None);
}
/// <summary>
/// Determines whether the action should be considered.
/// </summary>
/// <param name="actionRouteParameterValue">The action route parameter value.</param>
/// <param name="actionDescriptor">The associated <see cref="HttpActionDescriptor">action descriptor</see>.</param>
/// <param name="route">The associated <see cref="IHttpRoute">route</see>.</param>
/// <param name="apiVersion">The <see cref="ApiVersion">API version</see> to consider the controller for.</param>
/// <returns>True if the action should be explored; otherwise, false.</returns>
protected override bool ShouldExploreAction(string actionRouteParameterValue, HttpActionDescriptor actionDescriptor, IHttpRoute route, ApiVersion apiVersion)
{
Arg.NotNull(actionDescriptor, nameof(actionDescriptor));
Arg.NotNull(route, nameof(route));
Arg.NotNull(apiVersion, nameof(apiVersion));
if (!(route is ODataRoute))
{
return(base.ShouldExploreAction(actionRouteParameterValue, actionDescriptor, route, apiVersion));
}
if (Options.UseApiExplorerSettings)
{
var setting = actionDescriptor.GetCustomAttributes <ApiExplorerSettingsAttribute>().FirstOrDefault();
if (setting?.IgnoreApi == true)
{
return(false);
}
}
var model = actionDescriptor.GetApiVersionModel();
if (model.IsApiVersionNeutral || model.DeclaredApiVersions.Contains(apiVersion))
{
return(true);
}
if (model.DeclaredApiVersions.Count == 0)
{
model = actionDescriptor.ControllerDescriptor.GetApiVersionModel();
return(model.IsApiVersionNeutral || model.DeclaredApiVersions.Contains(apiVersion));
}
return(false);
}
/// <summary>
/// Gets the API versions declared by the action.
/// </summary>
/// <param name="actionDescriptor">The <see cref="HttpActionDescriptor">action</see> to evaluate.</param>
/// <returns>A <see cref="IReadOnlyList{T}">read-only list</see> of <see cref="ApiVersion">API versions</see>
/// declared by the action.</returns>
public static IReadOnlyList <ApiVersion> GetApiVersions(this HttpActionDescriptor actionDescriptor) => actionDescriptor.GetApiVersionModel().DeclaredApiVersions;
/// <summary> /// Gets a value indicating whether the action is API version neutral. /// </summary> /// <param name="actionDescriptor">The <see cref="HttpActionDescriptor">action</see> to evaluate.</param> /// <returns>True if the action is API version neutral (e.g. "unaware"); otherwise, false.</returns> public static bool IsApiVersionNeutral(this HttpActionDescriptor actionDescriptor) => actionDescriptor.GetApiVersionModel().IsApiVersionNeutral;
/// <summary> /// Gets the API version information associated with a action. /// </summary> /// <param name="action">The <see cref="HttpActionDescriptor">action</see> to evaluate.</param> /// <returns>The <see cref="ApiVersionModel">API version information</see> for the action.</returns> public static ApiVersionModel GetApiVersionModel(this HttpActionDescriptor action) => action.GetApiVersionModel(Explicit);