How to document Swagger/Swashbuckle parameter descriptions when using [FromQuery]

In a standard .NET Core 2.2 Api project with Swashbuckle.AspNetCore 5.0.0-rc2:

[HttpGet]
public ActionResult GetSomeData([FromQuery] SomeDataRequest request) {
    return File(returnImage(), "image/png");
}

The definition of SomeDataRequest

public class SomeDataRequest {
  /// <summary>
  /// Description 1
  /// </summary>
  [Description("description 1")]
  public string foo;

  /// <summary>
  /// Description 2
  /// </summary>
  [Description("description 2")]
  public string bar;
}

When I bring up the Swagger UI, it doesn’t show any kind of descriptions for the properties of SomeDataRequest.

As you can see I tried the Description attribute and the XML comments. Nothing seems to work.

[rgelb]

@davidkmitrais So let’s say you have 2 projects.

api.csproj – this project has Controller actions for your API entities.csproj – this project contains entities that you either pass in or return to/from the API.

You generate the XML documentation file for both, which results in api.xml and entities.xml. These files get placed in their respective bin/debug directories. And then the Startup.cs in your Api.cs has Swagger declaration to read the xml documentation:

services.AddSwaggerGen(c => {
    c.SwaggerDoc("v1", new Info { Title = "Widgets Images", Version = "v1" });
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
    ...

You can see the problem here, right? It’s only getting api.xml because that it’s in the executing directory. So you need to somehow bring entities.xml to the same directory. To do, that I defined a post-build step for the api project:

copy /Y $(ProjectDir)..\entities\bin\$(ConfigurationName)\netstandard2.0\entities.xml $(TargetDir)

You might have to fudge directory names a little bit if you are not using .net core 2.x

Now after every build, entities.xml will be in the same folder as api.xml. The last step is to let Swagger know about. We do this by extending AddSwaggerGen code a bit:

var entitiesXmlPath = Path.Combine(AppContext.BaseDirectory, "entities.xml");
c.IncludeXmlComments(entitiesXmlPath);

I hope this helps.

[utarn]

@rgelb Thanks! I just add GenerateDocumentationFile to all of referencing .csproj files without post build setting. Once the main project is compiled, the all the xml files are copied to the same directory as the main project is.

  <PropertyGroup>  
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>