Cómo agregar una descripción del método en la interfaz de usuario de Swagger en la aplicación WebAPI

Solución:

Esto está bien documentado en el proyecto: https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

---

Incluir descripciones de comentarios XML

Para mejorar los documentos generados con descripciones amigables para los humanos, puede anotar acciones y modelos del controlador con Comentarios Xml y configurar Swashbuckle para incorporar esos comentarios en el Swagger JSON generado:

1 – Abra el cuadro de diálogo Propiedades de su proyecto, haga clic en la pestaña “Crear” y asegúrese de que “Archivo de documentación XML” esté marcado. Esto producirá un archivo que contiene todos los comentarios XML en el momento de la compilación.

En este punto, cualquier clase o método que NO esté anotado con comentarios XML desencadenará una advertencia de compilación. Para suprimirlo, introduzca el código de advertencia “1591” en el campo “Suprimir advertencias” del cuadro de diálogo de propiedades.

2 – Configure Swashbuckle para incorporar los comentarios XML en el archivo en el Swagger JSON generado:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new Info
        {
            Title = "My API - V1",
            Version = "v1"
        }
     );

     var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
     c.IncludeXmlComments(filePath);
}

3 – Anote sus acciones con resumen, comentarios y etiquetas de respuesta:

/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public Product GetById(int id)

4 – También puede anotar tipos con etiquetas de resumen y ejemplo:

public class Product
{
    /// <summary>
    /// The name of the product
    /// </summary>
    /// <example>Men's basketball shoes</example>
    public string Name { get; set; }

    /// <summary>
    /// Quantity left in stock
    /// </summary>
    /// <example>10</example>
    public int AvailableStock { get; set; }
}

5 – Reconstruya su proyecto para actualizar el archivo de comentarios XML y navegue hasta el punto final Swagger JSON. Observe cómo las descripciones se asignan a los campos Swagger correspondientes.

NOTA: También puede proporcionar descripciones de Swagger Schema anotando sus modelos de API y sus propiedades con etiquetas de resumen. Si tiene varios archivos de comentarios XML (por ejemplo, bibliotecas separadas para controladores y modelos), puede invocar el método IncludeXmlComments varias veces y todos se fusionarán en el Swagger JSON generado.

---

Siguiendo las instrucciones cuidadosamente, debería obtener algo que se parezca a:
https://swashbucklenetcore.azurewebsites.net/swagger/

Para proyectos ASP.Net Core:

1. instalar el paquete nuget Swashbuckle.AspNetCore.Annotations

2. Utilice el atributo SwaggerOperation para métodos como [SwaggerOperation(Summary = "Write your summary here")]

3. Habilite las anotaciones en el método de inicio ConfigureServices de la siguiente manera:

           services.AddSwaggerGen(c =>
       {
           c.EnableAnnotations();
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
       });
   

4. Para excluir el método público de aparecer en swagger ui use el atributo [ApiExplorerSettings(IgnoreApi = true)]. Es útil porque estos métodos pueden romper la fanfarronería por alguna razón.

Lanzamiento del proyecto, vaya a localhost:[port number]/ fanfarronear y disfrutar.

Usamos atributos adicionales para agregar los detalles requeridos a la documentación de swagger:

    [SwaggerOperationSummary("Add a new Pet to the store")]
    [SwaggerImplementationNotes("Adds a new pet using the properties supplied, returns a GUID reference for the pet created.")]
    [Route("pets")]
    [HttpPost]
    public async Task<IHttpActionResult> Post()
    {
        ...
    }

Y luego, en su configuración de swagger, asegúrese de aplicar estos filtros:

config.EnableSwagger("swagger",
           c =>
           {
               c.OperationFilter<ApplySwaggerImplementationNotesFilterAttributes>();
               c.OperationFilter<ApplySwaggerOperationSummaryFilterAttributes>();

El código de los filtros:

public class ApplySwaggerImplementationNotesFilterAttributes : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        var attr = apiDescription.GetControllerAndActionAttributes<SwaggerImplementationNotesAttribute>().FirstOrDefault();
        if (attr != null)
        {
            operation.description = attr.ImplementationNotes;
        }
    }
}

public class ApplySwaggerOperationSummaryFilterAttributes : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        var attr = apiDescription.GetControllerAndActionAttributes<SwaggerOperationSummaryAttribute>().FirstOrDefault();
        if (attr != null)
        {
            operation.summary = attr.OperationSummary;
        }
    }
}

---

---

Utiliza Nuestro Buscador