Minimal APIs

[Megasware128]

ASP.NET Core 6 Preview 6 introduces OpenAPI support for minimal APIs. It does this by exposing an API Explorer from Endpoint metadata builder.Services.AddEndpointsApiExplorer(). This works correctly with Swashbuckle but doesn't with NSwag. NSwag loads without errors but the swagger.json doesn't contain any paths. Got some sample code bellow. (Working) Swashbuckle code has been commented out:

using System;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();

//builder.Services.AddSwaggerGen(c =>
//{
//    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Description = "Docs for my API", Version = "v1" });
//});

builder.Services.AddOpenApiDocument();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

//SwaggerBuilderExtensions.UseSwagger(app);

//app.UseSwaggerUI(c =>
//{
//    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
//});

app.UseOpenApi();
app.UseSwaggerUi3();

app.MapGet("/", () => "Hello World!");

app.Run();

[Megasware128]

Alright. I've been looking through the source code and I understand now this generator only supports ControllerActionDescriptor's and the Endpoint API Explorer exposes ActionDescriptor's.

[RicoSuter]

Alright. I've been looking through the source code and I understand now this generator only supports ControllerActionDescriptor's and the Endpoint API Explorer exposes ActionDescriptor's.

Wouldnt it be quite simple to add support for this?

[Megasware128]

I guess so. Just not sure where to start

[bradygaster]

Thanks for directing me to this issue @RicoSuter. I'll link to it from an existing issue the team has where we're tracking many of the OpenAPI issues we want to remember to work on throughout the minimal APIs work.

Here's code i worked up to try to test NSwag:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(settings =>
{
    settings.Title = "Minimal API";
    settings.Version = "v1";
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    app.UseOpenApi();
    app.UseSwaggerUi3();
}

app.MapGet("/", () => "Hello World!");

app.Run();

When I run this, I get an OpenAPI doc, but it lacks all operations. I presume this is due to NSwag's reliance on ControllerActionDescriptor. Since, essentially, minimal APIs don't require controllers (but does support them), folks who optimize for the minimal style don't "just work."

[RicoSuter]

I've created a simple PR, needs tests and also there is one big TODO - how to get the operation ID when there is no method name?

#3678

/cc @captainsafia

Currently trying to get NSwag solution to run in VS2022, but a lot of older .NET Framworks are not supported anymore, etc.
Probably it's time to drop all the legacy support sooner than later... we cannot support more than Microsoft ;-)

[captainsafia]

I've created a simple PR, needs tests and also there is one big TODO - how to get the operation ID when there is no method name?

We took a stab at a strategy for setting the endpoint name automatically using the method group name in dotnet/aspnetcore#35439 but ended up reverting it because it wasn't super reliable for names that might conflict across namespaces and it relied on some hacky assumptions about the way generated type names would be produced.

Would it be possible to reuse the same semantic currently used for controllers? AKA a combination of the HttpMethod and the endpoint route.

[RicoSuter]

Would it be possible to reuse the same semantic currently used for controllers? AKA a combination of the HttpMethod and the endpoint route.

I think this is the best option now... however it would be nice if there would be some way to define the operation name on app.MapGet

[RicoSuter]

So i created a minimal API like

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using System.Threading.Tasks;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(settings =>
{
    settings.Title = "Minimal API";
    settings.Version = "v1";
});

var app = builder.Build();

app.UseDeveloperExceptionPage();
app.UseOpenApi();
app.UseSwaggerUi3();

app.MapGet("/", (r) => Task.FromResult("Hello world!"));

app.Run();

With this csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <ProjectReference Include="..\NSwag.AspNetCore\NSwag.AspNetCore.csproj" />
  </ItemGroup>
</Project>

However API explorer does not report anything (IApiDescriptionGroupCollectionProvider.Items is empty)?
Any ideas?

/cc @captainsafia

[RicoSuter]

Minimal APIs are now working my PR: #3678
Please have a look and test it yourself.

[RicoSuter]

First experimental version will be released with v13.14.0