英文:

.NET 7/8 How do I provide a description/summary on a Group with Minimap APIs?

问题 {#heading}

我正在添加一组最小的API，如下所示：

var myapi = app.MapGroup("myapi").WithTags("My API").WithOpenApi();

// and then
myapi.MapGet("/", GetAllStuff).WithName("GetAllStuff");
myapi.MapGet("/{id}", GetSomeStuff).WithName("GetSomeStuff");

这样可以为我提供Swagger UI，但我目前无法为这两个API添加描述，换句话说，无法为该组添加摘要。有什么建议吗？ 英文:

I am adding a group of minimal APIs like this:

var myapi = app.MapGroup("myapi").WithTags("My API").WithOpenApi();

// and then
myapi .MapGet($"/", GetAllStuff).WithName("GetAllStuff");
myapi .MapGet($"/{id}", GetSomeStuff).WithName("GetSomeStuff");

This gives me the Swagger UI, but I am currently not able to have a description for both the APIs, in other words, a summary of the Group. Any ideas?

答案1 {#1}

得分: 1

我看不到一种内置的方式（就像端点的`WithDescription`一样）来提供这个数据，但你可以使用[文档过滤器][1]来解决：

```csharp
public class TagDescriptionsDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Tags = new List<OpenApiTag>
        {
            new OpenApiTag { Name = "我的 API", Description = "我的 API 做了某些事情" }
        };
    }
}

以及

builder.Services.AddSwaggerGen(opts => opts.DocumentFilter<TagDescriptionsDocumentFilter>());

显然，标签名称必须匹配。

<details>
<summary>英文:</summary>

I don\&#39;t see a build-in way (like `WithDescription` for endpoints) to provide this data but you can workaround with https://github.com/domaindrivendev/Swashbuckle.AspNetCore#document-filters:

public class TagDescriptionsDocumentFilter : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
swaggerDoc.Tags = new List<OpenApiTag>
{
new OpenApiTag { Name = "My API", Description = "My API does something" }
};
}
}

And

builder.Services.AddSwaggerGen(opts => opts.DocumentFilter<TagDescriptionsDocumentFilter>());

Obviously tag names must match.

\[![enter image description here](http://static.51tbox.com/static/2024-11-29/col/5abb230bdcf32a4ee599d8b2db11a3ee/c7ecb85cb080438c94a71aeda0f899ac.png.jpg)\]http://static.51tbox.com/static/2024-11-29/col/5abb230bdcf32a4ee599d8b2db11a3ee/c7ecb85cb080438c94a71aeda0f899ac.png.jpg


\</details\>