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);
}

我正在尝试让示例响应以大摇大摆的方式出现，但它始终默认响应示例如下：

正如您从上面的代码中看到的那样，我创建了一个 "PackageCreatedExample" class ，我希望它被拾起并大摇大摆地使用，但它只是被忽略了。我尝试使用注释 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

根据作者的说法，这种方法不应该再使用了（官方readme的link). This section描述了描述和例子应该如何处理。

简而言之，你必须

删除所有注释并改用以下注释：

/// <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)

在“项目”->“属性”->“生成”选项卡->“输出”部分中选中 XML documentation file 以启用生成 XML 文档
配置 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);
}

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

PackageCreate.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; }
}

Documentation.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; }
}

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

ASP.net Core - SwaggerResponseExample not outputting specified example

c#

asp.net-core

asp.net-web-api

swagger

swagger-ui