Как определить описания контроллеров в ASP.NET Core Swagger (Swashbuckle.AspNetCore)?

Я пробую Swagger в проекте ASP.NET Core WebApi, и все работает нормально, кроме описаний контроллеров.

Например, у меня есть UredskoPoslovanjeController, а описание в пользовательском интерфейсе Swagger - UredskoPoslovanje, и я не могу найти способ его изменить.

Единственное найденное мной решение указано здесь Однако я думаю, что это противоречит версиям API, поскольку управление версиями использует тот же атрибут [ApiExplorerSettings(GroupName = "v2")].

Вот для этой части swagger.json: УредскоПослование в 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() });
                }
            }            
        }
    }

Я ожидал бы "Уредско послованье API" в качестве описания контроллера, но этого не происходит - Скриншот пользовательского интерфейса swagger

Есть идеи, как правильно установить описание контроллера?

Спасибо, Марио

Стоит ли изучать PHP в 2026-2027 годах?
Стоит ли изучать PHP в 2026-2027 годах?
Привет всем, сегодня я хочу высказать свои соображения по поводу вопроса, который я уже много раз получал в своем сообществе: "Стоит ли изучать PHP в...
Поведение ключевого слова "this" в стрелочной функции в сравнении с нормальной функцией
Поведение ключевого слова "this" в стрелочной функции в сравнении с нормальной функцией
В JavaScript одним из самых запутанных понятий является поведение ключевого слова "this" в стрелочной и обычной функциях.
Приемы CSS-макетирования - floats и Flexbox
Приемы CSS-макетирования - floats и Flexbox
Здравствуйте, друзья-студенты! Готовы совершенствовать свои навыки веб-дизайна? Сегодня в нашем путешествии мы рассмотрим приемы CSS-верстки - в...
Тестирование функциональных ngrx-эффектов в Angular 16 с помощью Jest
В системе управления состояниями ngrx, совместимой с Angular 16, появились функциональные эффекты. Это здорово и делает код определенно легче для...
Концепция локализации и ее применение в приложениях React ⚡️
Концепция локализации и ее применение в приложениях React ⚡️
Локализация - это процесс адаптации приложения к различным языкам и культурным требованиям. Это позволяет пользователям получить опыт, соответствующий...
Пользовательский скаляр GraphQL
Пользовательский скаляр GraphQL
Листовые узлы системы типов GraphQL называются скалярами. Достигнув скалярного типа, невозможно спуститься дальше по иерархии типов. Скалярный тип...
5
0
6 289
2
Перейти к ответу Данный вопрос помечен как решенный

Ответы 2

Согласно документации, вы можете аннотировать действия и модели контроллера с помощью XML-комментариев. Не сам контроллер.

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

Значит, нет возможности это сделать? Я видел примеры на других языках, где это можно сделать с помощью нотации @Api, поэтому я надеялся, что есть способ сделать это и в ASP.NET Core.

mariob 25.05.2018 13:47

Swashbuckle - это открытый исходный код, и вы можете изменить его так, как хотите. Я полагаю, это зависит от того, насколько сильно вам нужна эта функциональность.

Hans Kilian 25.05.2018 14:44

Я не вижу нигде на связанной странице, где говорится, что контроллеры не могут оставлять комментарии к ним. Пожалуйста, посмотрите мой ответ. По умолчанию он не включен, но доступен.

Brad Bruce 23.07.2020 21:02
Ответ принят как подходящий

По умолчанию комментарии к контроллеру не включаются. У метода IncludeXmlComments есть версия, которая принимает логическое значение, чтобы указать, следует ли использовать комментарии XML контроллера. Приведенный ниже код взят из моего метода 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

Другие вопросы по теме