API Explorer Options

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 have the following configuration settings:

GroupNameFormat
SubstituteApiVersionInUrl
SubstitutionFormat
DefaultApiVersion
DefaultApiVersionParameterDescription
AssumeDefaultVersionWhenUnspecified
ApiVersionParameterSource
AddApiVersionParametersWhenVersionNeutral
RouteConstraintName
FormatGroupName

Format Group Name

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}";
                    } );

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.

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.

Keyboard shortcuts