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

Question

我在 .NET6 中有一个小项目，其中包含最少的 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

目前对 Open API 文档的最小 API 支持是 quite minimal and does not allow adding descriptions/summaries as far as I can see. There is a feature planned for .NET 7 to add descriptions. Also soon Swashbuckle should consider EndpointMetadata for annotations。

也相关 issue.

Answer 2

您可以使用 this guide。它使用 Swashbuckle 对我有用。有一些带有最少 API 的扩展方法。外观如下：

app.MapGet(“/books”, async (BooksDB db) =>
await db.Books.ToListAsync()
)
.Produces<List<Book>>(StatusCodes.Status200OK)
.WithName(“GetAllBooks”).WithTags(“Getters”);

Answer 3

套餐Swashbuckle.AspNetCore.Annotations6.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

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

Add Swagger description to minimal .NET6 APIs

c#

swagger

swagger-ui

.net-6.0

minimal-apis