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

Question

My api endpoint:

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

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.

I've placed descriptions in the Description attribute and in the XML comments as suggested by This answer. Nothing seems to work.

Am I missing something simple?

P.S. It does seem to work in other scenarios when FromQuery isn't used.

P.P.S. Resolved... The problem was that the SomeDataRequest class was in another project and therefore its XML documentation file wasn't being processed by Swashbuckle.

Answer 1

While it seems that this question is old and OP managed to solve his problem, nobody wrote an full answer to this question. So in order to help people like me who might be trying to figure out the same issue, I'm going to write what worked for me (which seems to be the same solution as the OP one).

This issue seems to happen when you have multiple assemblies and you're only generating documentation files for your main assembly and not the other ones in which your DTO class might be located.

So to fix it, you need to do two things: turn on documentation generation on every assembly (or at least the ones were your DTOs are located) and tell swashbuckle where these xml files are.

---

The first step is to turn on the option for generation documentation on each assembly. In my project, the configuration that managed to generate the xml file with the documentation was the following:

 <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
 </PropertyGroup>

After turning this in every assembly, the documentation files were output to same folder were my main assembly dll files were located, which was \Project.API\bin\Debug\netcoreapp2.2.

If this does not work for you, you could try setting the output path explicitly using the DocumentationFile compiler option.

---

After that, you need to tell Swashbuckle where those xml files are. If they're all in the main assembly dll folder, you can use the following snippet to collect them all.

List<string> xmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml", SearchOption.TopDirectoryOnly).ToList();
xmlFiles.ForEach(xmlFile => swaggerGenOptions.IncludeXmlComments(xmlFile));

Disclaimer: This snippet was not made by me. I took it from the issue on github about the same topic. It just looks for the xml files by probing the main assembly build folder.

If this does not work for you, you will need to find where your xml files are located and add them one by one using IncludeXmlComments().

After that you should get documentation for your parameters to show on the Swagger page.

Just for information I did this on a .NET Core 2.2 app using Swashbuckle 3.0.0, but I believe this will still work for newer versions of the library, since the thread on github about this issue has quite recent answers.