/// <summary>
/// Adds or replaces the configured <see cref="IApiExplorer">API explorer</see> with an implementation that supports API versioning.
/// </summary>
/// <param name="configuration">The <see cref="HttpConfiguration">configuration</see> used to add the API explorer.</param>
/// <param name="setupAction">An <see cref="Action{T}">action</see> used to configure the provided options.</param>
/// <returns>The newly registered <see cref="VersionedApiExplorer">versioned API explorer</see>.</returns>
/// <remarks>This method always replaces the <see cref="IApiExplorer"/> with a new instance of <see cref="VersionedApiExplorer"/>.</remarks>
public static VersionedApiExplorer AddVersionedApiExplorer(this HttpConfiguration configuration, Action <ApiExplorerOptions> setupAction)
{
Arg.NotNull(configuration, nameof(configuration));
Arg.NotNull(setupAction, nameof(setupAction));
Contract.Ensures(Contract.Result <VersionedApiExplorer>() != null);
var options = new ApiExplorerOptions(configuration);
setupAction(options);
var apiExplorer = new VersionedApiExplorer(configuration, options);
configuration.Services.Replace(typeof(IApiExplorer), apiExplorer);
return(apiExplorer);
}
static IOptions <ApiExplorerOptions> NewOptions(IServiceProvider serviceProvider, Action <ApiExplorerOptions> setupAction)
{
Contract.Requires(serviceProvider != null);
Contract.Requires(setupAction != null);
Contract.Ensures(Contract.Result <IOptions <ApiExplorerOptions> >() != null);
var versioningOptions = serviceProvider.GetService <IOptions <ApiVersioningOptions> >();
var options = new ApiExplorerOptions();
if (versioningOptions != null)
{
options.DefaultApiVersion = versioningOptions.Value.DefaultApiVersion;
}
setupAction(options);
return(new OptionsWrapper <ApiExplorerOptions>(options));
}
static IOptions <ApiExplorerOptions> NewOptions(IServiceProvider serviceProvider, Action <ApiExplorerOptions> setupAction)
{
Contract.Requires(serviceProvider != null);
Contract.Requires(setupAction != null);
Contract.Ensures(Contract.Result <IOptions <ApiExplorerOptions> >() != null);
var versioningOptions = serviceProvider.GetService <IOptions <ApiVersioningOptions> >()?.Value;
var options = new ApiExplorerOptions();
if (versioningOptions != null)
{
options.DefaultApiVersion = versioningOptions.DefaultApiVersion;
options.ApiVersionParameterSource = versioningOptions.ApiVersionReader;
options.AssumeDefaultVersionWhenUnspecified = versioningOptions.AssumeDefaultVersionWhenUnspecified;
}
setupAction(options);
return(new OptionsWrapper <ApiExplorerOptions>(options));
}
public static void SetVersionApiExplorer(this ApiExplorerOptions options)
{
options.GroupNameFormat = "'v'VV";
}
/// <summary>
/// Attempts to update the relate path of the specified API description and remove the corresponding parameter according to the specified options.
/// </summary>
/// <param name="apiDescription">The <see cref="ApiDescription">API description</see> to attempt to update.</param>
/// <param name="options">The current <see cref="ApiExplorerOptions">API Explorer options</see>.</param>
/// <returns>True if the <paramref name="apiDescription">API description</paramref> was updated; otherwise, false.</returns>
public static bool TryUpdateRelativePathAndRemoveApiVersionParameter(this ApiDescription apiDescription, ApiExplorerOptions options)
{
Arg.NotNull(apiDescription, nameof(apiDescription));
Arg.NotNull(options, nameof(options));
if (!options.SubstituteApiVersionInUrl || !(apiDescription is VersionedApiDescription versionedApiDescription))
{
return(false);
}
var parameter = versionedApiDescription.ParameterDescriptions.FirstOrDefault(p => p.ParameterDescriptor is ApiVersionParameterDescriptor pd && pd.FromPath);
if (parameter == null)
{
return(false);
}
var relativePath = apiDescription.RelativePath;
var token = '{' + parameter.ParameterDescriptor.ParameterName + '}';
var value = versionedApiDescription.ApiVersion.ToString(options.SubstitutionFormat, InvariantCulture);
var newRelativePath = relativePath.Replace(token, value);
if (relativePath == newRelativePath)
{
return(false);
}
apiDescription.RelativePath = newRelativePath;
apiDescription.ParameterDescriptions.Remove(parameter);
return(true);
}
private static void ConfigureApiExplorerOptions(ApiExplorerOptions options)
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
}
internal static void SetApiExplorerOptions(ApiExplorerOptions options)
{
options.GroupNameFormat = VersionFormat;
options.SubstituteApiVersionInUrl = true;
}
public static void ApplyUrlBasedVersioning(ApiExplorerOptions options)
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
}
private static void ConfigureVersionedApiExplorer(ApiExplorerOptions options)
{
// add the versioned api explorer, which also adds IApiVersionDescriptionProvider service
// note: the specified format code will format the version as "'v'major[.minor][-status]"
options.GroupNameFormat = "'v'VVV";
}
