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

笔者认为，这种方法不应该再使用(联系). 这 节 的官方readme描述了如何处理描述和示例。

简而言之，您必须

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. 在Project下启用生成XML文档 -> Properties -> Build tab -> Check... XML documentation file 在输出部分
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. 为您的输入模型类的属性添加示例注释。

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

文档.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; }
}