Endpoint level deprecations and deprecation behavior

[KPHIBYE]

While trying to deprecate a single Minimal API endpoint without affecting other endpoints of the same version (as #1167 brought forth) I noticed some behavior I didn't expect and wanted to inquire if this is a bug or intended.

1. When setting options.Policies.Deprecate(1) and enabling ReportApiVersions, the deprecated field is not set to true in the OpenAPI doc for any v1 endpoint and no api-deprecated-versions header is returned. Is it intended that the deprecation policy does not really deprecate affected endpoints?
2. Even when enabling my OpenApiDeprecationTransformer to set the property to true on endpoints with the ObsoleteAttribute, the endpoint still does not return an api-deprecated-versions header. I realize the transformer only touches the document, so is there a way to set the endpoint earlier in the pipeline to deprecated so that the deprecation headers are handled correctly?
3. I have not found an easy way in the examples to deprecate a single endpoint without changing any other endpoints to a different version because even when applying HasDeprecatedApiVersion(1) on a specific endpoint, it is applied to the whole v1 version set. Is per-endpoint deprecation intentionally out of scope? If so, what's the recommended way to signal that a single endpoint is going away while the rest of the version stays current?

I am under the impression that I have misunderstood a fundamental concept of this library which is giving me the wrong expectations.

Minimal reproduction example (tested on SDK 10.0.201):

1. Please run with --no-cache
2. Uncomment options.Document.AddOperationTransformer() — deprecation information now appears in http://localhost:5000/swagger

#!/usr/bin/env dotnet
#:sdk Microsoft.NET.Sdk.Web

#:package Microsoft.OpenApi@2.11.0
#:package Microsoft.AspNetCore.OpenApi@10.0.10
#:package Asp.Versioning.OpenApi@10.0.0-rc.1
#:package Swashbuckle.AspNetCore.SwaggerUI@10.2.3

#:property PublishAot=false
#:property GenerateDocumentationFile=true
#:property InterceptorsNamespaces=$(InterceptorsNamespaces);Microsoft.AspNetCore.OpenApi.Generated
#:property Nullable=enable
#:property NoWarn=$(NoWarn);1591

using Asp.Versioning;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

var builder = WebApplication.CreateSlimBuilder(args);

builder.Services
    .AddApiVersioning(static options =>
    {
        options.ReportApiVersions = true;
        options.Policies.Deprecate(1);
    })
    .AddApiExplorer(static setup => setup.GroupNameFormat = "'v'VVV")
    .AddOpenApi(static options =>
    {
        //options.Document.AddOperationTransformer<OpenApiDeprecationTransformer>();
    });

var app = builder.Build();

app.NewVersionedApi()
   .MapGroup("api")
   .MapToDoEndpoints();

app.MapOpenApi().WithDocumentPerVersion();
app.UseSwaggerUI(options =>
{
    options.EnableFilter();
    options.EnableTryItOutByDefault();

    foreach (var description in app.DescribeApiVersions())
    {
        string name = description.GroupName;
        string url = $"/openapi/{name}.json";
        options.SwaggerEndpoint(url, name);
    }
});

app.Run();



public static class ToDoEndpoints
{
    public static IEndpointRouteBuilder MapToDoEndpoints(this IEndpointRouteBuilder endpoints)
    {
        var group = endpoints.MapGroup("ToDo").WithTags("ToDo").HasApiVersion(1);

        group.MapGet("{id}", GetToDo);
        group.MapGet("plain/{id}", GetPlainToDo);

        return endpoints;
    }

    [Obsolete("Use the plain endpoint instead")]
    private static Results<Ok<ToDoDto>, NotFound> GetToDo(Guid id)
    {
        return TypedResults.Ok(new ToDoDto(id, "Example", "Create a minimal repro example."));
    }

    private static ToDoDto GetPlainToDo(Guid id) => new ToDoDto(id, "Example", "Create a minimal repro example.");
}

public sealed record ToDoDto(Guid Id, string Title, string Description);

public sealed class OpenApiDeprecationTransformer : IOpenApiOperationTransformer
{
    public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
    {
        var obsolete = context.Description.ActionDescriptor.EndpointMetadata.OfType<ObsoleteAttribute>().FirstOrDefault();

        if (obsolete is null)
        {
            return Task.CompletedTask;
        }

        operation.Deprecated = true;

        if (!string.IsNullOrEmpty(obsolete.Message))
        {
            string obsoleteMessage = $"This endpoint is deprecated: '{obsolete.Message}'";
            operation.Description = string.IsNullOrEmpty(operation.Description)
                ? obsoleteMessage
                : $"{obsoleteMessage}\n\n{operation.Description}";
        }

        return Task.CompletedTask;
    }
}

[commonsensesoftware]

I believe the I see the disconnect. API versions are ultimately just metadata and are applied via:

public interface IApiVersionProvider
{
    ApiVersionProviderOptions Options { get; }
    IReadOnlyList<ApiVersion> Versions { get; }
}

where the options are:

[Flags]
public enum ApiVersionProviderOptions
{
    None,
    Deprecated = 1,
    Advertised = 2,
    Mapped = 4,
}

The options are more comprehensive for scenarios than [Obsolete] cannot express. In 99% of the cases, [Obsolete] is never considered.

For better clarity, consider:

[ApiController]
[ApiVersion(1.0, Deprecated = true)]
[ApiVersion(2.0)]
[Obsolete]
[Route("[controller]")]
public class ExampleController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok();
}

This is referred to as version interleaving. In this scenario, what does [Obsolete] mean? What does it apply to? IApiVersionProvider instances can be expressed by attribute or by conventions. This is similarly confusing when you apply conventions which have [Obsolete] applied. The meanings can even be contradictory.

Custom conventions are supported, but the VersionByNamespaceConvention is the only one provided out-of-the-box. This specific convention honors [Obsolete] because you can't express deprecated any other way, there is only one representation, and it wasn't worth creating a new attribute. For example:

namespace My.Api.V1; // ← 1.0 is extracted from the namespace as a convention

[Obsolete] // ← the convention treats this ApiVersionProviderOptions.Deprecated
[Route("[controller]")]
public class ExampleController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok();
}

This applies to Minimal APIs as well. It's technically possible to interleave with this convention, but I don't think I've ever seen it. That makes it very hard to reason about. For more information, see the Version by Namespace wiki topic.

The second miss is how policies work. The applied API versions are the source of truth. A policy does not set or change the API version for endpoints. It merely defines the policy for a particular API version. A policy is purely informational. The API Explorer extensions collate API versions by the endpoints that define them. If all endpoints for an API version are deprecated, then the entire API version is also deprecated. This is expressed and retrievable via the IApiVersionDescriptionProvider service, which is the entry point for OpenAPI. Each API version description has:

public class ApiVersionDescription
{
    public ApiVersion ApiVersion { get; }
    public string GroupName { get; }
    public bool IsDeprecated { get; }
    public SunsetPolicy? SunsetPolicy { get; }
    public DeprecationPolicy? DeprecationPolicy { get; }
}

All of the collation and associated policy information is gathered for you. This information is also available at the API level as well as the endpoint level. Although an endpoint is technically an API, that's not typically how service authors think about or refer to them. You would call it the Get Order operation on the Orders API. Deprecation and sunsetting usually occur on the entire API for a particular version, not individual endpoints.

To circle back around as to why your configuration didn't meet your expectations.

Define the Logical API Formally

An API is a collated set of endpoints. If you give it a logical name, you never need to use WithTags. For controllers, the logical name is inferred from the controller name. For Minimal APIs, you just define it yourself and all endpoints are collated under it.

app.NewVersionedApi("ToDo").MapGroup("api").MapToDoEndpoints();

Define Deprecated API Versions

The implementation is the source of truth. If you have/want a deprecated API version, then you need to express that. [Obsolete] is not considered by most of the built-in conventions.

public static IEndpointRouteBuilder MapToDoEndpoints(this IEndpointRouteBuilder endpoints)
{
    // applies to all endpoints in the group, but endpoints can express their versions independently too
    var group = endpoints.MapGroup("ToDo").HasDeprecatedApiVersion(1);

    group.MapGet("{id}", GetToDo);
    group.MapGet("plain/{id}", GetPlainToDo);

    return endpoints;
}

Define a Deprecation Policy

The deprecation policy doesn't deprecate an API version, it defines what the policy is for a deprecated API version. This information is output in client responses when reported and OpenAPI. The versioned HttpClient support enables a client to detect when an API version they are using has become deprecated.

options.Policies.Deprecate(1)
                .Effective(new DateTimeOffset(2026, 10, 1))
                .Link("policies/deprecation.html")
                    .Title("Version Deprecation Policy")
                    .Type("text/html");

options.Policies.Sunset(1)
                .Effective(new DateTimeOffset(2027, 1, 1))
                .Link("policies/sunset.html")
                    .Title("Version Sunset Policy")
                    .Type("text/html");

This attaches a deprecation policy that informs clients that API version 1.0 will be deprecated on 2026-10-01. A link to a HTML page is provided for a human being to read. You're not required to provide a link, but it can be useful; especially for OpenAPI. If you only use .Deprecate(1), the policy will know the API version is deprecated, but that is already known from the API version itself. This minimal configuration isn't very useful and doesn't add anything.

One of the reasons the policy is separate is because you can define an effective date in the future. This allows you to deploy a change that indicates when an API will become deprecated before it actually does. If no effective date is specified, it's assumed to be deprecated now.

In a similar fashion, you may want to indicate the sunset policy. The difference is that sunsetting an API means it's gone for good whereas a deprecated API is still supported and addressable. The deprecation policy indicates when the API is deprecated and the sunset policy indicates when you're shutting it down and it won't exist anymore. These are closely related, but distinct policies. Each policy also yields different headers to clients about the policy.

The api-deprecated-versions header has long indicated the deprecated versions, but it can't indicate when an API version is/was deprecated nor can it define when it will be sunset. A deprecated API reports the deprecation header as well as the sunset header, if there are corresponding policies.

A Deprecation Transformer is Unnecessary

Asp.Versioning.OpenApi uses the information from Asp.Versioning.Mvc.ApiExplorer to bridge the ApiDescription.IsDeprecated extension property to OpenApiOperation.Deprecated. For this to work, then API version associated with the operation must actually be deprecated. If policy information is available, it is also added. The example projects show this behavior in action.

---

I hope that helps clarify things.