Does Swagger (Asp.Net Core) have a controller description?

Question

I'm building a REST service that will host multiple controllers (microservices). As a whole, lets call the service "Bob". So swagger displays "Bob" / "A collection of Bob Microservices". Then the controller names are listed. Right now, it just shows XYZ, ABC, etc. Is there a way to maybe have swagger show "XYZ - A collection of XYZ APIs" or something of that sort?

Seems like swagger shows the ///Summary on the methods, but not on the controllers.

Answer 1

If you are using Swashbuckle 4.0.x and ASP.NET Core 2.x, you may have something like this which also works by including the NuGet package for Swashbuckle.AspNetCore.Annotations.

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Swashbuckle.AspNetCore.Annotations;

namespace MyExample.Controllers
{
/// <summary>
/// Example of a .NET Core controller based on the controller name
/// api/[controller] on ValuesController becomes api/values
/// endpoint: "/Values" from [controller] and name of controller , which is "ValuesController"
/// </summary>
[Route("[controller]")]
[ApiController]
[SwaggerTag("This is an example controller generated by ASP.NET Core 2.x")]
public class ValuesController : ControllerBase
{
...
}

Then my Startup.cs swagger code in the ConfigureServices Method looks like this, (edited to include contribution from Iain Carlin to include controller header comments) :

services.AddSwaggerGen(c =>
{
    // Set Title and version
    c.SwaggerDoc("v1", new Info { Title = "My Example API", Version = "v1", Description = "The API for my application" });
    // Set the comments path for the Swagger JSON and UI.
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // pick comments from classes, including controller summary comments
    c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true); 
    // _OR_ enable the annotations on Controller classes [SwaggerTag], if no class comments present
    c.EnableAnnotations();
});

Then my Controller will get decorated