Solución:
Si está utilizando Swashbuckle 4.0.xy ASP.NET Core 2.x, es posible que tenga algo como esto que también funciona al incluir el paquete NuGet para 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
{
...
}
Entonces mi código Swagger Startup.cs en el método ConfigureServices se ve así, (editado para incluir la contribución de Iain Carlin para incluir comentarios del encabezado del controlador):
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();
});
Entonces mi controlador se decorará
Estaba buscando una respuesta similar y esperaba poder usar los comentarios XML resumidos en la clase del controlador para proporcionar la descripción del controlador. Resulta que puede hacer esto agregando includeControllerXmlComments: true en la configuración de Swagger en el inicio:
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);
});Por lo que entonces:
/// <summary>
/// My controller description
/// </summary>
[Route("api/[controller]")]
[ApiController]se muestra como:
¿Hay alguna forma de mostrar arrogancia “XYZ – Una colección de API XYZ”?
Si. Esta es una de las formas más sencillas. La versión ASP.NET Core de Swagger aprovecha la ApiExplorerSettings atributo. Puede configurar el GroupName.
public class BobController
{
[ApiExplorerSettings(GroupName="XYZ - A collection of XYZ APIs")]
public IActionResult MyAction()
{
...
}
}
El nombre del grupo aparece en la interfaz de usuario de Swagger con las acciones del grupo enumeradas como operaciones debajo.
Editar: Aquí hay una idea basada en el comentario de SledgeHammer.
Swagger ASP.NET Core usa un IApiDescriptionGroupCollectionProvider para construir sus grupos de descripción. Podríamos implementar el nuestro, usando el valor predeterminado ApiDescriptionGroupCollectionProvider en busca de inspiración y registre a nuestro proveedor durante Startup.ConfigureServices. Nuestra implementación haría que el ApiDescriptionGroups() método devuelve el GroupName asociado con el controlador de cada acción. Entonces podríamos poner el ApiExplorerSettings atributo en cada controlador en lugar de en cada acción.