dotnet / aspnetcore

ASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.

Home Page:https://asp.net

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Move OpenAPI extension methods to M.A.Builder namespace

captainsafia opened this issue · comments

Background and Motivation

In preview4, we introduced support for an OpenAPI package that included extension methods on the then RouteHandlerBuilder (now IEndpointBuilder) for constructing an OpenApiOperation from an endpoint. These extension methods were placed in the Microsoft.AspNetCore.OpenApi namespace.

For consistency with the rest of the ecosystem, we want to move these extension methods to the Microsoft.AspNetCore.Builder namespace.

Proposed API

- namespace Microsoft.AspNetCore.OpenApi;
+ namespace Microsoft.AspNetCore.Builder;

public static class OpenApiRouteHandlerBuilderExtensions
{
  ...
}

Usage Examples

Before Change

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;

var app = WebApplication.Create();
app.UseRequestDecompression();
app.MapGet("/", ...).WithOpenApi();

With Change

using Microsoft.AspNetCore.Builder;
// No additional namespace references needed

var app = WebApplication.Create();
app.UseRequestDecompression();
app.MapGet("/", ...).WithOpenApi();

Alternative Designs

Not applicable.

Risks

None, API waas introduced in .NET 7 so no risk of breaking change and delta allows us to confirm with the standard for builder extension methods elsewhere.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

  • The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
  • The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
  • Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

API review notes:

  • Noticed two OpenApiRouteHandlerBuilderExtensions types, let's rename this one to something like OpenApiEndpointConventionBuilderExtensions
+ namespace Microsoft.AspNetCore.Builder;

- public static class OpenApiRouteHandlerBuilderExtensions
+ public static class OpenApiEndpointConventionBuilderExtensions
{
  ...
}

API approved!