Skip to content

API Explorer Options

Jump to bottom
Chris Martinez edited this page Dec 30, 2022 · 7 revisions

The API Explorer options 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:

The ApiExplorerOptions has the following configuration settings:

1: Applies to ASP.NET Core only

The ODataApiExplorerOptions extends the above options with the following additional settings:

1: Applies to ASP.NET Web API only

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 OpenAPI 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.

Format Group Name

Applies to ASP.NET Core only

This option allows you to define an optional FormatGroupNameCallback, which will provide the current group name and formatted API version. By default, the formatted API version is used as the group name and is the most logical choice. A developer, however, may specify their own group name in a variety of ways such as [ApiExplorerSettings(GroupName = "Custom")]. When a developer explicitly sets a group name, that name is honored. If, and only if, a developer sets both a custom group name and defines a FormatGroupName callback, the method will be invoked to produce a combination of both.

Consider the following controller:

[ApiVersion( 1.0 )]
[ApiExplorerSettings( GroupName = "Sales" )]
[Route( "[controller]" )]
public class OrderController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok();
}

A callback can be defined to control how the combination of the API version and group name will be formatted.

builder.Services.AddApiVersioning()
                .AddMvc()
                .AddApiExplorer(
                    options =>
                    {
                        // the default is ToString(), but we want "'v'major[.minor][-status]"
                        options.GroupNameFormat = "'v'VVV";

                        // if we have both parts, decided how to format the group
                        // from the example: "Sales - v1"
                        options.FormatGroupName = (group, version) => $"{group} - {version}";
                    } );

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.

Add API Version Parameters When Version-Neutral

This options let's you define whether an API version parameter is generated for version-neutral APIs. A version-neutral API does not require an API version; however, you may not want a client to know the API is version-neutral. By setting AddApiVersionParametersWhenVersionNeutral = true, an API version parameter will be explored, even though it is not required. The default value is false.

Route Constraint Name

This option defines the name of the route constraint used in route templates. The default value derives from ApiVersioningOptions.RouteConstraintName and should not be changed.

OData-Specific Options

Use API Explorer Settings

Applies to ASP.NET Web API with OData only

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.

Use Qualified Names

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.

Metadata Options

This option allows you to determine whether the OData metadata ($metadata) and service document (/) are explored as available endpoints. The available options are: None, ServiceDocument, Metadata, or All. The default value is None.

Ad Hoc Model Builder

This property returns an VersionedODataModelBuilder that can be used for building ad hoc Entity Data Models (EDMs) that are used when defining the query options for APIs that do not use the full OData stack. Some OData query options can only be set via Model Bound settings. This builder constructs an ad hoc EDM that will contain those settings solely for the purposes of API exploration and without opting into any other OData-specific features. For more information see the OData query options topic.

Related Entity Id Parameter Description

This option enables you to specify the description for OData related entity links. The default value is "The identifier of the related entity." OData related entity links appear in $ref requests. This description is used to describe dynamic parameters such as the $id query parameter.

Clone this wiki locally