具有最少 API 的文档查询参数

Question

我尝试使用

RouteHandlerBuilder

扩展方法将一些 OpenAPI 文档放在最小 API 中的查询参数上。我还没有找到任何关于如何实现这一目标的示例或文档。

        group
            .MapGet(
                "/paymentCard",
                async (
                    string osbToken,
                    [FromServices] IDataversePaymentCardService paymentCardService
                ) =>
                {
                    // Removed for brevity
                    return Results.Ok();
                }
            )
            .Produces<PaymentCard?>(StatusCodes.Status200OK)
            .WithCommonErrorResponses()
            .WithSummary("Find a payment card based on osbToken (XYZ handle)")
            .WithOpenApi(static operation =>
            {
                operation.Parameters.Add(new OpenApiParameter
                {
                    Name = "osbToken",
                    Description = "The handle from XYZ, which must start with 'ca_'",
                    Required = true,
                    Schema = new OpenApiSchema { Type = "string" }
                });

                return operation;
            });

如果我添加

In = ParameterLocation.Query

，我会得到 2 个相同的，但没有描述。

感谢您的帮助。

Answer 1

假设您正在使用 .NET 8 和

Swashbuckle.AspNetCore

。您可以使用

Swashbuckle.AspNetCore.Annotations

包：

<ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.11"/>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="7.1.0" />
    <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="7.1.0" />
</ItemGroup>

启用注释处理：

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

并添加描述：

app
    .MapGet(
        "/paymentCard",
        (
            [SwaggerParameter("The handle from XYZ, which must start with 'ca_'")] string osbToken
        ) => ...
    )

结果：