33

I'm using SwaggerResponse attributes to decorate my api controller actions, this all works fine, however when I look at the generated documentation the description field for parameters is empty.

Is a there an attribute based approach to describe action parameters (rather than XML comments)?

0

4 Answers 4

54

With the latest Swashbuckle, or better said at least the Swashbuckle.AspNetCore variant which I'm using, the Description field for parameters can now be displayed correctly as output.

It does require the following conditions to be met:

  • XML comments must be enabled and configured with Swagger
  • Parameters should be explicitly decorated with either [FromRoute], [FromQuery], [FromBody] etc.
  • The same for the method type (get/post/put etc.), which should be decorated with [Http...]
  • Describe the parameter as usual with a <param ...> xml comment

A full sample looks like this:

/// <summary>
/// Short, descriptive title of the operation
/// </summary>
/// <remarks>
/// More elaborate description
/// </remarks>
/// <param name="id">Here is the description for ID.</param>
[ProducesResponseType(typeof(Bar), (int)HttpStatusCode.OK)]
[HttpGet, Route("{id}", Name = "GetFoo")]
public async Task<IActionResult> Foo([FromRoute] long id)
{
    var response = new Bar();
    return Ok(response);
}

Which produces the following output:

Swagger output with parameter description

5
  • 4
    Is there a way to inherit these comments? For example when I have a crudcontroller. And all my controllers (customer, client, orders, ) etc.. inherit from this controller. Can I specify the comments / description for the parameters in the base controller and let my customer controller inherit?
    – Enrico
    Commented Nov 22, 2017 at 12:46
  • 2
    In additions to the requirements mentioned in the answer, it is also a necessary prerequisite for descriptions to show up to first generate the xml comments for your project via <PropertyGroup><DocumentationFile> in your csproj and then register these in your services.AddSwaggerGen() via IncludeXmlComments(filePath);.
    – Felix K.
    Commented Mar 20, 2018 at 19:12
  • I get error FromUriAttribute could not be found. Do I really have to install a new package Microsoft.AspNet.WebApi.Core just for the decorator? Commented Dec 20, 2022 at 20:19
  • @JohnHenckel I believe FromUri is deprecated after AspNet Core 2.2. Perhaps that's why you can't find it? In recent versions you can use [FromQuery] and [FromRoute].
    – Juliën
    Commented Dec 21, 2022 at 10:27
  • 1
    @Juliën thanks, but my error was something else. I had a syntax error in my XML comment. After I fixed that, the parameter showed up great!! no attribute is required!! Commented Dec 21, 2022 at 16:03
9

You should confirm you are allowing Swagger to use XML comments

httpConfig.EnableSwagger(c => {
                if (GetXmlCommentsPath() != null) {
                    c.IncludeXmlComments(GetXmlCommentsPath());
                }
...
...
);

protected static string GetXmlCommentsPath() {
    var path = HostingEnvironment.MapPath("path to your xml doc file");
    return path;
}

You should also check you are generating XML doc for your desired project. Under your desired project Properties (Alt + Enter on top of the project or Right Click -> Properties) -> Build -> Check XML documentation file

0

For completeness sake, when using latest version of Swashbuckle.AspNetCore (2.1.0) and Swashbuckle.SwaggerGen/Ui (6.0.0), enable Xml documentation file generation in your project's Build

Then the following to your ConfigureServices() method:

services.ConfigureSwaggerGen(options =>
{
    options.SingleApiVersion(new Info
    {
        Version = "v1",
        Title = "My API",
        Description = "API Description"
    });
    options.DescribeAllEnumsAsStrings();

    var xmlDocFile = Path.Combine(AppContext.BaseDirectory, $"{_hostingEnv.ApplicationName}.xml");
    if (File.Exists(xmlDocFile))
    {
        var comments = new XPathDocument(xmlDocFile);
        options.OperationFilter<XmlCommentsOperationFilter>(comments);
        options.ModelFilter<XmlCommentsModelFilter>(comments);
    }
});
1
  • 2
    Just to point out that from Swashbuckle 5.0 on (and probably all versions of Swashbuckle.AspNetCore) you should be using options.SchemaFilter<XmlCommentsSchemaFilter>(comments) instead of options.ModelFilter<XmlCommentsModelFilter>(comments); See: github.com/domaindrivendev/… Commented Jun 3, 2018 at 21:30
0

Use Annotations. Package is Swashbuckle.AspNetCore.Annotations. https://github.com/domaindrivendev/Swashbuckle.AspNetCore#swashbuckleaspnetcoreannotations

Like this. description for parameters

1
  • Duplicate answer, adds no new information.
    – Cristi
    Commented Mar 14, 2023 at 13:58

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.