ASP.net Core - SwaggerResponseExample 未输出指定示例

Question

我使用 ASP.net Core 和 swagger，创建了以下方法和详细文档：

/// <summary>Creates a package with the requested information.</summary>
/// <param name="createPackage">The package information to create.</param>
/// <response code="201" cref="PackageCreatedExample">Created</response>
/// <returns><see cref="PackageCreated"/> package created.</returns>
[HttpPost]
[SwaggerResponse(201, "Package created", typeof(PackageCreated))]
[SwaggerResponse(400, "Validation failure", typeof(ApiErrorResult))]
[SwaggerResponseExample(201, typeof(PackageCreatedExample))]
public async Task<IActionResult> CreatePackage(PackageCreate createPackage)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(new ApiErrorResult(ModelState));
    }

    var createdPackageInfo = new PackageCreated();

    // Created item and location returned.
    return CreatedAtAction(nameof(GetPackage), new { createdPackageInfo.Id, Version = "2" }, createdPackageInfo);
}

我试图获取一个以 swagger 形式出现的示例响应，但它总是默认响应示例，如下所示：

正如您从上面的代码中看到的，我创建了一个“PackageCreatedExample”类，我希望在 swagger 中使用该类，但它只是被忽略了。我尝试使用注释response code="201" cref="PackageCreatedExample"并编写SwaggerResponseExample属性，但都没有被采纳。这是我的示例代码：

public class PackageCreatedExample : IExamplesProvider<PackageCreated>
    {
        public PackageCreated GetExamples()
        {
            return new PackageCreated {
                Outcome = "PackageCreated",
                Reference = "6178",
                ShippingDocumentation = new List<Documentation> {
                    new Documentation {
                        Document = "JVBERi0xLjMNCjEgMCBvYmoNCjw8DQovVHlwZSAvQ2F...",
                        Format = "Pdf",
                        Type = DocumentationType.TYPE3
                    }
                },
                ReturnsDocumentation = new List<Documentation> {
                    new Documentation {
                        Document = "YmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL1BhZ2VzIDQgMJVBERi0xLjMNCjEgMCBv...",
                        Format = "doc",
                        Type = DocumentationType.TYPE4
                    }
                }
            };
        }
    }

我究竟做错了什么？

预先感谢您的任何指点！

Answer 1

据作者称，不应再使用此方法（链接）。官方自述文件的这一部分描述了如何处理描述和示例。

简而言之，你必须

1. 删除所有注释并改用以下内容：

/// <summary>Creates a package with the requested information.</summary>
/// <param name="createPackage">The package information to create.</param>
/// <returns>package created.</returns>
/// <response code="201">Created</response>
/// <response code="400">Validation failure</response>
[HttpPost]
[ProducesResponseType(typeof(PackageCreated), 201)]
[ProducesResponseType(typeof(ApiErrorResult), 400)]
public async Task<IActionResult> CreatePackage(PackageCreate createPackage)       

2. XML documentation file在“项目”->“属性”->“构建”选项卡-> “签入输出”部分中启用生成 XML 文档
3. 配置 swagger 以使用生成的 XML 文件

services.AddSwaggerGen(c =>
{
  c.SwaggerDoc("v1",
      new OpenApiInfo
      {
          Title = "My API - V1",
          Version = "v1"
      }
   );

   var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
   c.IncludeXmlComments(filePath);
}

4. 将示例注释添加到输入模型类的属性中：

包创建.cs

public PackageCreate 
{
  // Built-in type
  /// <summary>
  /// Outcome value
  /// </summary>
  /// <example>PackageCreated</example>
  public string Outcome { get; set; }

  // Custom class -> comment its properties in Documentation.cs
  public Documentation { get; set; }

  // Array type -> comment the properties in Documentation.cs
  public IList<Documentation> { get; set; }
}

文档.cs：

public Documentation
{
  /// <summary>
  /// Document name
  /// </summary>
  /// <example>YmoNCjw8DQovVHlwZSAvQ2F0YWxvZw0KL1BhZ2VzIDQgMJVBERi0xLjMNCjEgMCBv</example>
  public string Document { get; set; }

  /// <summary>
  /// Document format
  /// </summary>
  /// <example>doc</example> 
  public string Format { get; set; }
}