Question

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

[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不会为成员使用///三斜杠注释。我的其他控制器使用FromBody和///三斜杠注释可以很好地使用它们。似乎底部的“模型”部分得到了注释，但是当我看控制器时，我正在浅绿色部分中谈论模型描述。

我已经查看了模式注册表，并且描述确实存在。

编辑：使用Swashbuckle 5.0 Beta。

编辑＃2：似乎也没有从架构注册表中为表单参数选择示例值。

有什么想法吗？

Answer 1

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

此外，在配置Swagger时，请确保其包含xml注释。

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

Answer 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上。

Asp.Net Core Swagger / FromForm ///（三斜杠）注释未收到？

2 个答案: