Swashbuckle：多态性不适用于外部 nuget 包

Question

在我们的 API 中，当用户调用端点时，我们希望从外部 Nuget 包返回一个对象。

这个对象有几个属性。 其中之一称为Action 。 此属性具有IPaymentResponseAction类型，但可以是一组不同的操作类型（您可以在此处查看它们）。

生成的 swagger 不知道这些操作，也不会生成所需的代码。 即使设置了多态性设置。

    services.AddSwaggerGen(c =>
            {
                c.EnableAnnotations();
                c.UseOneOfForPolymorphism();
            });

有没有办法让这些对象出现在我的招摇中？ 也许有一些自定义SwaggerGenOptions ？

Answer 1

这可以使用Swashbuckle.AspNetCore.Annotations 包来完成。 根据 API 设计，您可以使用以下方法之一。

响应模式不依赖于响应代码

这种方法利用了在响应模式中使用oneOf 的优势。 这个想法是让 Swashbuckle 生成一个具有oneOf的响应模式：

responses:
  '200':
    description: Success
    content:
      application/json:
        schema:
          oneOf:
            - $ref: '#/components/schemas/CheckoutAwaitAction'
            - $ref: '#/components/schemas/CheckoutBankTransferAction'
            - $ref: '#/components/schemas/CheckoutDonationAction'
            - $ref: '#/components/schemas/CheckoutOneTimePasscodeAction'
            # ...

以下是您需要做的：

1. 添加UseOneOfForPolymorphism和SelectSubTypesUsing选项，您AddSwaggerGen通话; 确保您的SelectSubTypesUsing在您的 API 从控制器返回的所有所需实现中解析IPaymentResponseAction接口：

    services.AddSwaggerGen(c => { // ... c.UseOneOfForPolymorphism(); c.SelectSubTypesUsing(baseType => { if (baseType == typeof(IPaymentResponseAction)) { return new[] { typeof(CheckoutAwaitAction), typeof(CheckoutBankTransferAction), typeof(CheckoutDonationAction), typeof(CheckoutOneTimePasscodeAction), // ... }; } return Enumerable.Empty<Type>(); });

2. 将SwaggerResponse注释添加到您的控制器方法中。 仅指定IPaymentResponseAction接口。

    [HttpGet] [SwaggerResponse((int)HttpStatusCode.OK, "response description", typeof(IPaymentResponseAction))] public IPaymentResponseAction GetPaymentAction() { // ...

这将为您提供Swagger-UI所需的架构：

请注意， Swagger-UI不支持“示例值”部分，如果模式有一个oneOf定义：它只是显示在第一解析类型响应样本SelectSubTypesUsing电话。

响应模式取决于响应代码

这看起来不像你的情况，但我仍然想把它作为一种选择。

如果不同响应码的响应模式不同，可以直接在控制器中指定对应的类型：

[HttpPost]
[SwaggerResponse((int)HttpStatusCode.Created, "response description", typeof(CheckoutAwaitAction))]
[SwaggerResponse((int)HttpStatusCode.OK, "response description", typeof(CheckoutBankTransferAction))]
// ...
public IPaymentResponseAction PostPaymentAction()
{
    // ...