API Explorer Options

The ApiExplorerOptions class allows you to configure, customize, and extend the default behaviors when you add API exploration support. The configuration options are specified by providing a callback to the appropriate extension method:

ASP.NET Web API

configuration.AddVersionedApiExplorer( options => { /* configure options */ } );

ASP.NET Web API with OData

configuration.AddODataApiExplorer( options => { /* configure options */ } );

ASP.NET Core

services.AddVersionedApiExplorer( options => { /* configure options */ } );

Prior to 3.0, the setup is:

services.AddMvcCore()
        .AddApiExplorer()
        .AddVersionedApiExplorer( options => { /* configure options */ } );

ASP.NET Core with OData

services.AddODataApiExplorer( options => { /* configure options */ } );

The ApiExplorerOptions class has the following configuration settings:

• GroupNameFormat
• SubstituteApiVersionInUrl
• SubstitutionFormat
• DefaultApiVersion
• DefaultApiVersionParameterDescription
• AssumeDefaultVersionWhenUnspecified
• ApiVersionParameterSource

OData-Specific Options

• UseApiExplorerSettings
• UseQualifiedOperationNames
• QueryOptions

Group Name Format

The group name format is the format string that is applied to the current API version being explored. This resultant, formatted string is used as the group name for the explored API. The group name is often used in tools such as Swagger and Swashbuckle to logically group APIs together. For more information and examples on the format specifiers for an API version, see the Custom API Version Format Strings topic.

Substitute API Version in URL

This option will instruct the API explorer to substitute API version parameters that are in the route template with the corresponding API version value. When an API version parameter value is substituted, that parameter is also removed from the parameters associated with the API description. This option is useful for service authors that version by URL segment and want the API version value automatically populated. For example, the route template api/v{version}/resource for API version 1.0 will become api/v1/resource and the API version parameter will be removed. The default value is false.

Substitution Format

This option is meant to be paired with the SubstituteApiVersionInUrl option. This affords service authors control over how the API version value is formatted before being substituted into route templates. The default value is VVV, but it can be any value according to the available formatting options.

Default API Version

This option defines what the default ApiVersion will be for a service without explicit API version information. The default value is derived from ApiVersioningOptions.DefaultApiVersion and should not be changed.

Default API Version Parameter Description

This option defines what the default description for API version parameters will be. The default value is: "The requested API version".

Assume Default Version When Unspecified

This option enables support for clients to make requests with implicit API versioning. This option is used during API exploration to determine whether the API version parameter is required. The default value is derived from ApiVersioningOptions.AssumeDefaultVersionWhenUnspecified and should not be changed.

API Version Parameter Source

This option configures how the API exploration process discovers API version parameters. The default value derives from ApiVersioningOptions.ApiVersionReader and should not be changed.

OData-Specific Options

Use API Explorer Settings

OData controllers are not explored by default. The API explorer for OData services does not initially honor this setting so that OData APIs will be discovered. You might decide, however, to use the API explorer settings to explicitly define which OData services should be explored. You must set this property to a value of true in order for the API explorer to respect API explorer settings.

UseQualifiedOperationNames

The OData API Explorer is responsible for building URLs that refer to your entity sets, functions, and actions. This property determines whether the constructed URLs use qualified names. The default value is false. The ODataUriResolver instance configured for your application must be configured to match the generated URLs (ex: UnqualifiedCallAndEnumPrefixFreeResolver).

Query Options

This option allows you to configure OData query options. The configuration for query options can be expressed purely by convention, through the use of supported OData query attribute, or both. The default behavior will always apply conventions from OData query attributes without additional configuration. For more information see the OData query options topic.

This option is available in 3.0+