如何在 ASP.NET Core Swagger (Swashbuckle.AspNetCore) 中定义控制器描述？答案

【问题标题】：How to define controller descriptions in ASP.NET Core Swagger (Swashbuckle.AspNetCore)?如何在 ASP.NET Core Swagger (Swashbuckle.AspNetCore) 中定义控制器描述？
【发布时间】：2018-05-24 13:50:12
【问题描述】：

我正在 ASP.NET Core WebApi 项目中尝试 Swagger，一切正常 - 除了控制器描述。

例如，我有 UredskoPoslovanjeController，而 Swagger UI 中的描述是 UredskoPoslovanje，我找不到更改它的方法。

列出了我找到的唯一解决方案here 但是，我认为这与 API 版本冲突，因为版本控制使用完全相同的属性 [ApiExplorerSettings(GroupName="v2")]

这里是这部分的 swagger.json： UredskoPoslovanje part in swagger.json

我的控件是这样定义的：

   /// <summary>
    /// Uredsko poslovanje API
    /// </summary>
    [Authorize]
    [Route("api/[controller]")]
    public class UredskoPoslovanjeController : Controller
    {
        private LinkDbContext ctx;

        public UredskoPoslovanjeController(LinkDbContext ctx)
        {
            this.ctx = ctx;
        }

        /// <summary>
        /// Vraća broj pismena za zadani OIB
        /// </summary>
        /// <param name="OIB">OIB korisnika za koji se traži broj pismena</param>
        /// <returns>Vraća broj pronađenih pismena</returns>
        /// <response code="200">Vraća broj pismena za traženi OIB</response>
        /// <response code="400">OIB ne postoji</response>        
        /// <response code="401">Nemate pristup metodi (neispravna autorizacija)</response>        
        [HttpGet("BrojPismena/{oib}")]
        public ActionResult<BrojPismenaModel> DajBrojPismena(string OIB)
        {
            if (string.IsNullOrWhiteSpace(OIB)) return BadRequest("OIB ne smije biti prazan");
            else
            {
                var osoba = ctx.Osoba.FirstOrDefault(x => x.Oib == OIB);
                if (osoba == null) return BadRequest($"Osoba s OIB-om '{OIB}' ne postoji!");
                else
                {
                    return Ok(new BrojPismenaModel() { OIB = OIB, BrojPismena = ctx.UpPismeno.Count() });
                }
            }            
        }
    }

我希望“Uredsko poslovanje API”作为控制器描述，但这不会发生 - swagger ui screenshot

知道如何正确设置控制器描述吗？

谢谢，马里奥

【问题讨论】：

标签： c# asp.net-core swagger swagger-ui swashbuckle

【解决方案1】：

默认情况下不包括控制器的 cmets。 IncludeXmlComments 方法有一个版本，它采用布尔值来指示是否应使用控制器 XML cmets。下面的代码来自我的 Startup : ConfigureServices 方法。

原文：

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

新：

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath, true);  // <== Added the true here, to show the controller description

【讨论】：

【解决方案2】：

根据文档，您可以使用 XML cmets 注释控制器操作和模型。不是控制器本身。

https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

【讨论】：

那么，有没有办法做到这一点？我已经看到其他语言的示例可以使用 @Api 表示法来完成，所以我希望在 ASP.NET Core 中也有一种方法。
Swashbuckle 是开源的，你可以修改它来做你想做的事。我猜这取决于你对这个功能的渴望程度。
我在链接页面中没有看到任何地方表明控制器无法对它们发表评论。请看我的回答。默认不开启，但可以使用。