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

Neat and easy method using NSwag for .NET Core 3.1. Just add the code below and you get a nice description for controllers and the APIs. Plus some description at the top of the swagger page.

Startup.cs - method: public void ConfigureServices(IServiceCollection services)

        services.AddSwaggerDocument(config =>
        {
            config.OperationProcessors.Add(
                    new AspNetCoreOperationSecurityScopeProcessor("JWT"));
            // Add summary to the controller
            config.UseControllerSummaryAsTagDescription = true;
            // Add JWT authorization option at the top
            config.AddSecurity("JWT", Enumerable.Empty<string>(), new OpenApiSecurityScheme
            {
                Type = OpenApiSecuritySchemeType.ApiKey,
                Name = "Authorization",
                In = OpenApiSecurityApiKeyLocation.Header,
                Description = "Type into the textbox: Bearer {your JWT Token}"
            });
            config.PostProcess = document =>
            {
                document.Info.Version = "1";
                document.Info.Title = "title";
                document.Info.Description = "description";
            };
        });

Method: public void Configure(IApplicationBuilder app, IWebHostEnvironment env) Add this:

        //CONFIG: Configure NSwag
        app.UseOpenApi();
        app.UseSwaggerUi3();

Then, at the top of the controller class and methods, just add a summary, for example:

/// <summary>
/// your description
/// </summary>
[ApiController]
[Route(your route)]
public class NameController : ControllerBase

It will give a nice and clean as the live demo here: https://swagger.io/tools/swagger-ui/

Answer 2

There is a new attribute, replacing the old [SwaggerTag(...)] in NSwag.Annotations:

[OpenApiTag("This is name", Description = "This is description")]

Which results to:

Note, the first attribute name has to be specified, you can either keep the name the same or rename the controller.

Unfortunately, it seems that there is no easy solution for the ///summary comments to be added to the docs. This approach worked without any extra configuration.

Answer 3

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

Answer 4

I was looking for a similar answer and hoping to be able to use the summary XML comments on the controller class to provide the controller description. Turns out you can do this by adding includeControllerXmlComments: true in the Swagger configuration in startup:

    services.AddSwaggerGen(c =>
    {
        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
    });

So then:

    /// <summary>
    /// My controller description
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]

displays as:

Answer 5

I know this is old, but just in case someone else lands here - looking for an answer for the core version - and for the sake of completeness, I'll leave another easy option. From the docs:

Customize Operation Tags (e.g. for UI Grouping)

The Swagger spec allows one or more "tags" to be assigned to an operation. The Swagger generator will assign the controller name as the default tag. This is particularly interesting if you're using the SwaggerUI middleware as it uses this value to group operations.

You can override the default tag by providing a function that applies tags by convention. For example, the following configuration will tag, and therefore group operations in the UI, by HTTP method:

services.AddSwaggerGen(c =>
{
    ...
    c.TagActionsBy(api => api.HttpMethod);
};

Using this way you could tag your endpoints using the logic that best fits your needs. You pass the lambda to the TagActionsBy method and return the tag you want.

For the sample you provided we could do:

services.AddSwaggerGen(c =>
{
    ...
    c.TagActionsBy(api => "XYZ - A collection of XYZ APIs");
};

Hope this helps!

Answer 6

You could also use SwaggerOperationAttribute for that:

public class MyController 
{
    [SwaggerOperation(Tags = new[] { "XYZ - A collection of XYZ APIs" })]
    public IActionResult MyAction() 
    {
    }
}

In Swashbuckle.AspNetCore version 1.0.0-rc3 the ApiExplorerSettingsAttribute is used to include an action in a specific Swagger document.

Answer 7

Is there a way to maybe have swagger show "XYZ - A collection of XYZ APIs"

Yes. Here is one of the easiest ways. The ASP.NET Core version of Swagger leverages the ApiExplorerSettings attribute. You can set the GroupName.

public class BobController 
{
    [ApiExplorerSettings(GroupName="XYZ - A collection of XYZ APIs")]
    public IActionResult MyAction() 
    {
        ...
    }
}

The group name appears in the Swagger UI with the group's actions listed as operations underneath.

Edit: Here is an idea based on SledgeHammer's comment.

Swagger ASP.NET Core uses an IApiDescriptionGroupCollectionProvider to build its description groups. We could implement our own, using the default ApiDescriptionGroupCollectionProvider for inspiration, and register our provider during Startup.ConfigureServices. Our implementation would make the ApiDescriptionGroups() method return the GroupName associated with each action's controller. Then we could put the ApiExplorerSettings attribute on each controller instead of onto each action.