How to define controller descriptions in ASP.NET Core Swagger (Swashbuckle.AspNetCore)?

Question

I am trying Swagger in ASP.NET Core WebApi project and everything works fine - except controller descriptions.

For instance, I have UredskoPoslovanjeController and description in Swagger UI is UredskoPoslovanje and I can not find a way to change it.

Only solution I found is listed here However, I think this is in conflict with API versions since versioning uses exact same attribute [ApiExplorerSettings(GroupName="v2")]

Here is swagger.json for this part: UredskoPoslovanje part in swagger.json

And my controlle is defined like this:

   /// <summary>
    /// Uredsko poslovanje API
    /// </summary>
    [Authorize]
    [Route("api/[controller]")]
    public class UredskoPoslovanjeController : Controller
    {
        private LinkDbContext ctx;

        public UredskoPoslovanjeController(LinkDbContext ctx)
        {
            this.ctx = ctx;
        }

        /// <summary>
        /// Vraća broj pismena za zadani OIB
        /// </summary>
        /// <param name="OIB">OIB korisnika za koji se traži broj pismena</param>
        /// <returns>Vraća broj pronađenih pismena</returns>
        /// <response code="200">Vraća broj pismena za traženi OIB</response>
        /// <response code="400">OIB ne postoji</response>        
        /// <response code="401">Nemate pristup metodi (neispravna autorizacija)</response>        
        [HttpGet("BrojPismena/{oib}")]
        public ActionResult<BrojPismenaModel> DajBrojPismena(string OIB)
        {
            if (string.IsNullOrWhiteSpace(OIB)) return BadRequest("OIB ne smije biti prazan");
            else
            {
                var osoba = ctx.Osoba.FirstOrDefault(x => x.Oib == OIB);
                if (osoba == null) return BadRequest($"Osoba s OIB-om '{OIB}' ne postoji!");
                else
                {
                    return Ok(new BrojPismenaModel() { OIB = OIB, BrojPismena = ctx.UpPismeno.Count() });
                }
            }            
        }
    }

I would expect "Uredsko poslovanje API" as controller description, but that does not happen - swagger ui screenshot

Any idea how to properly set controller description?

Thanks, Mario

score 19 · Accepted Answer · answered Jul 23 '20 at 18:58

By default the comments for the controller are not included. The IncludeXmlComments method has a version that takes a boolean to indicate whether the controller XML comments should be used. The code below is from my Startup : ConfigureServices method.

Original:

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

New:

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath, true);  // <== Added the true here, to show the controller description

score 0 · Answer 2 · answered Mar 02 '23 at 08:54

You can annotate via SwaggerTag attribute

[ApiController]
[SwaggerTag("This is an example SwaggerTag")]
public class MyController : ControllerBase

as seen in Swashbuckle.AspNetCore.Annotations version 6.x

Make sure you have performed all what Brad Bruce has asked you to do.

score -1 · Answer 3 · answered May 24 '18 at 14:08

-1

Per the documentation, you can annotate controller actions and models with XML comments. Not the controller itself.

https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

answered May 24 '18 at 14:08

Hans Kilian

18,948
1
26
35

1

So, there is no way to do this? I have seen examples in other languages where this can be done with @Api notation, so I was hoping there is a way to do it in ASP.NET Core as well. – mariob May 25 '18 at 11:47
1

Swashbuckle is open source and you might be able to modify it to do what you want. Depends on how badly you want this functionality, I guess. – Hans Kilian May 25 '18 at 12:44
I don't see anywhere in the linked page where it states that controllers could not have a comment on them. Please see my answer. It's not on by default, but it is available. – Brad Bruce Jul 23 '20 at 19:02

How to define controller descriptions in ASP.NET Core Swagger (Swashbuckle.AspNetCore)?

3 Answers3