Asp.Net Core Swagger / FromForm ///（三斜杠）评论没有被拾起？答案

【问题标题】：Asp.Net Core Swagger / FromForm /// (triple slash) comments not picked up?Asp.Net Core Swagger / FromForm ///（三斜杠）评论没有被拾起？
【发布时间】：2021-02-20 00:16:49
【问题描述】：

我有一个如下所示的控制器方法：

[HttpPost]
[Consumes("application/x-www-form-urlencoded")]
[Produces("application/json")]
public async Task<IActionResult> GenerateTokenAsync([FromForm]TokenParameters tokenParameters)

TokenParameters 如下所示：

public class TokenParameters
{
    /// <summary>
    /// Specifies the grant type. Must be "password".
    /// </summary>
    [Required]
    public GrantType? grant_type
    {
        get;
        set;
    }

    /// <summary>
    /// Specifies the username.
    /// </summary>
    [Required]
    public string username
    {
        get;
        set;
    }

    /// <summary>
    /// Specifies the password.
    /// </summary>
    [Required]
    public string password
    {
        get;
        set;
    }
}

一切正常，但 Swagger UI 没有为成员选择 /// 三斜杠 cmets。我的其他控制器使用 FromBody 和 /// 三斜杠 cmets 可以正常工作。看起来底部的模型部分选择了 cmets，但是当我查看控制器时，我正在谈论浅绿色部分的模型描述。

我查看了架构注册表，确实有描述。

编辑：使用 Swashbuckle 5.0 Beta。

编辑 #2：它似乎也没有从模式注册表中获取表单参数的示例值。

有什么想法吗？

【问题讨论】：

您找到解决方案了吗？

标签： c# asp.net-core swagger swagger-ui

【解决方案1】：

确保您的项目选中了Generate xml documentation 选项。

另外，当您配置 Swagger 时，请确保它包含 xml cmets。

// Register the Swagger generator, defining one or more Swagger documents
services.AddSwaggerGen(c =>
{
  c.SwaggerDoc("v2", new Info { Title = "my API", Version = "v2" });

  // Set the comments path for the Swagger JSON and UI.
  var basePath = PlatformServices.Default.Application.ApplicationBasePath;
  var xmlPath = Path.Combine(basePath, "myapp.xml");
  c.IncludeXmlComments(xmlPath);
});

【讨论】：

正如我在帖子中提到的，除了 application/x-www-form-urlencoded 之外，cmets 无处不在。
hmmm 你在哪里检查“生成 XML 文档”选项？ IDE中有什么东西吗？哪一个？
docs.microsoft.com/en-us/dotnet/csharp/codedoc

【解决方案2】：

我也有这个问题。我的问题是我没有包含正确 XML 文档文件。我只包含Web 应用程序 XML 文档，而我的“创建选项”对象是从另一个程序集中定义的表单数据创建的。一旦我让这个程序集生成 XML 文档并将其包含在 swagger 配置中，我就能够获得每个表单字段项的描述。

这是我处理来自客户端的 POST 的控制器方法：

/// <summary>
/// Create a new very complex object.
/// </summary>
/// <param name="creationOptions">Very complex creation options</param>
/// <returns>The very complex object as a data transfer object.</returns>
[HttpPost]
[Consumes("application/x-www-form-urlencoded")]
public async Task<IActionResult> CreateVeryComplexObject([FromForm] VeryComplexObjectCreationOptions creationOptions) { }

添加 swagger 服务时，我包含了两个程序集的文档：

services.AddSwaggerGen(config =>
{
    // All my other swagger configuration here...

    config.IncludeXmlComments(System.IO.Path.Combine(AppContext.BaseDirectory, "MyService.API.Web.xml"));
    config.IncludeXmlComments(System.IO.Path.Combine(AppContext.BaseDirectory, "MyService.API.Contracts.xml"));
});

这是在 Swashbuckle 4.0.1 上。

【讨论】：

hmmm...什么是 AppContext？我没有