Does Swagger (Asp.Net Core) have a controller desc

问题:

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.

回答1:

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.

回答2:

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.

回答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 looks like this:

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
                c.IncludeXmlComments(xmlPath);
                // enable the annotations on Controller classes [SwaggerTag]
                c.EnableAnnotations();
            });

Then my Controller will get decorated

回答4:

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!

回答5:

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: