Asp.Net Core Swagger / FromForm /// (triple slash) comments not picked up?

user_5004822 0
Viewed 2263

I have a controller method that looks like this:

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

TokenParameters looks like this:

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

Everything works fine, but the Swagger UI is not picking up the /// triple slash comments for the members. My other controllers use FromBody and /// triple slash comments work fine with those. Seems like the model section at the bottom picks up the comments, but I'm talking about the model description in the light green section when I look at the controller.

I've looked in the schema registry, and the descriptions are indeed there.

EDIT: Using Swashbuckle 5.0 Beta.

EDIT #2: It also doesn't seem to pick up the example values from the schema registry for form parameters either.

Any ideas?

swagger-ui swagger asp.net-core c#
2 Answers

Make sure that your project has the Generate xml documentation option checked.

Also, when you configure Swagger, make sure to have it include the xml comments.

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

I too had this issue. My issue was that I was not including the correct XML documentation files. I was including only the web application XML documentation while I had my "creation options" object that was being created from the form data defined in another assembly. Once I had this assembly producing XML documentation and including it in the swagger configuration I was able to get descriptions for each form field item.

Here is my controller method handling the POST from the client:

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

When adding the swagger services I included the documentation from both assemblies:

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

This is on Swashbuckle 4.0.1.

user_134560
Related