将 Swagger 描述添加到最小的 .NET 6 API

Question

我在 .NET 6 中有一个小项目，其中包含类似的最少 API

app.MapGet("/clients",
     async (IClientRepository repo) =>
     {
          var results = await repo.GetClientsAsync();
          return mapper.Map<IEnumerable<ClientModel>>(results);
     });

在SwaggerUI我可以使用这个 API，但我找不到向其添加描述的方法（尽管在项目设置中我检查了创建 API XML 文档）。

如何添加 XML 注释？

Answer 1

目前，对最小 API 的开放 API 文档的支持相当少，据我所知，不允许添加描述/摘要。.NET 7计划有一项功能来添加描述。也很快Swashbuckle应该考虑EndpointMetadata进行注释。

还有相关问题。

更新

通过Swashbucklenuget 包的最新更新，Swashbuckle.AspNetCore.Annotations您可以向端点添加描述：

builder.Services.AddSwaggerGen(opts => opts.EnableAnnotations());

app.MapGet("/weatherforecast", () =>
{
    // Implementation
})
.WithMetadata(new SwaggerOperationAttribute(summary: "Summary", description: "Descritption Test"));

// Or

app.MapGet("/weatherforecast1", [SwaggerOperation(summary: "Summary1", description: "Descritption Test1")] () =>
{
    // Implementation
});

更新2

对于.NET 7和最新的Swashbuckle.AspNetCore封装WithDescription方法也可以使用：

builder.Services.AddSwaggerGen();
...

app.MapGet("/weatherforecast", () =>
{
    // implementation
})
.WithDescription("Some Method Description")
.WithOpenApi();

或者与EndpointDescriptionAttribute：

app.MapGet("/weatherforecast1", [EndpointDescription("Some Attribute description")] () =>
{
    // implementation
})
.WithOpenApi();

Answer 2

包裹Swashbuckle.AspNetCore.Annotations 6.3

...
builder.Services.AddSwaggerGen(c => c.EnableAnnotations());

var app = builder.build();

app.MapGet("/clients",
    [SwaggerOperation(
        Summary = "returns clients",
        Description = "more description on get `clients`")]
    [SwaggerResponse(200, "success")]
    [SwaggerResponse(500, "some failure")]
    async (IClientRepository repo) =>
    {
        var results = await repo.GetClientsAsync();
        return mapper.Map<IEnumerable<ClientModel>>(results);
    }).WithTags("Clients");

更多示例在这里 https://github.com/domaindrivendev/Swashbuckle.AspNetCore#enrich-operation-metadata

Answer 3

1.安装包

dotnet add package Swashbuckle.AspNetCore.Annotations

2. 编写代码

dotnet add package Swashbuckle.AspNetCore.Annotations

结果