Swashbuckle. Swagger без ограничений

Запись от Toros1992 размещена 07.06.2020 в 12:54

Хочу рассказать о своем опыте кастомизации Swagger'a, а точнее - схемы api-документации, которую он генерирует.

Если коротко, то сам Swagger - это набор инструментов для генерации схем в стандарте OpenApi
В своей работе наша команда использует стек .Net. В том числе - библиотеку Swashbuclkle, которая позволяет очень легко прикрутить Swagger к любому API, будь то ASP.NET или ASP.NET Core.

Но как и у любой высокоуровневой обертки, у Swashbuckle есть минус. Это естественные ограничения в использовании оборачиваемого функционала.

Для нашей команды таким ограничением стала невозможность глубокой кастомизации схем отдельных DTO, используемых в API.
Пара конкретных примеров:

Описание Enum.
Дело в том, что в Swagger можно отображать допустимый набор значений Enum либо как массив чисел, либо как массив имен.
Проблему решило бы наличие комментария к типу перечисления.
Но, несмотря на то, что в Swashbuckle есть атрибут SwaggerSchema, который позволяет добавлять поля к схеме типа (описание, флаг readonly и т.д.), этот атрибут запрещен для применения к Enum.
Отображение JsonExtensionData атрибута
Нас не устраивало как отображаются ключи полей, помеченных этим атрибутом. <*> - это недостаточно информативно.
Для решения этой проблемы у Swashbuckle мы не нашли никаких инструментов

Далее весь код для .Net Core
Мы решили, что нужно вручную редактировать схему под наши хотелки, но Swashbuckle разворачивается как Middleware, которое на запрос схемы API - генерирует ее на лету и отдает на клиент.

C#
1
2
3
4
5
6
7
8
9
    public void Configure(IApplicationBuilder app, IApplicationLifetime appLifeTime, IHostingEnvironment env)
    {
        //...
        app.UseSwagger().UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint($"/swagger/v1/swagger.json", "v1");
        });
        //...
    }

Поэтому был сделан еще один Middleware, который перехватывает ответ на запрос схемы, редактирует ее и отдает дальше на клиент.

C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
    public void Configure(IApplicationBuilder app, IApplicationLifetime appLifeTime, IHostingEnvironment env)
    {
        //...
        app.UseMiddleware<SwaggerCustomizeMiddleware>();
        app.UseSwagger().UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint($"/swagger/v1/swagger.json", "v1");
        });
        //...
    }
    class Middleware
    {
        RequestDelegate m_next;
 
        public Middleware(RequestDelegate next)
        {
            m_next = next;
        }
 
        public async Task InvokeAsync(HttpContext context)
        {
            if (context.Request.Path.Value.Contains("swagger.json"))
            {
                await SwaggerSchema(context);
                return;
            }
 
            await m_next.Invoke(context);
        }
 
        private async Task SwaggerSchema(HttpContext context)
        {
            using (var memory = new MemoryStream())
            {
                var respBody = context.Response.Body;
                context.Response.Body = memory;
 
                await m_next.Invoke(context);
 
                context.Response.Body = respBody;
 
                memory.Seek(0, SeekOrigin.Begin);
                using (var reader = new StreamReader(memory))
                {
                    var text = reader.ReadToEnd();
                    var schema = JObject.Parse(text);
                    foreach (JProperty item in schema ["components"]["schemas"])//расположение моделей может отличаться в различных версиях Swashbuckle
                    {
                        //кастомизируем модели
                    }
                    await context.Response.WriteAsync(schema.ToString());
                }
            }
        }
    }

Проблема в принципе решилась. Но этот код находится в базовых библиотеках, которые используют наши сервисы. Соответственно эта кастомизация будет работать одинаково для всех сервисов.
Хотелось бы иметь возможность, чтобы каждый отдельный сервис мог добавлять свои методы кастомизации схемы.
Используем для этого встроенный DI механизм ASP.Net Core
Выделим интерфейс, который будет предназначен только для одного - кастомизировать отдельный JProperty в схеме

C#
1
2
3
4
    public interface ISwaggerSchemaCustomizer
    {
        void Customize(JProperty model);
    }

А в нашем Middleware будем хранить набор экземпляров, реализующих данный интерфейс

C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
    class Middleware
    {
        RequestDelegate m_next;
        List<ISwaggerSchemaCustomizer> m_schemaCustomizers;
 
        public Middleware(RequestDelegate next)
        {
            m_next = next;
            m_schemaCustomizers = new List<ISwaggerSchemaCustomizer>
            {
                new EnumCustomizer(), // кастомайзеры по умолчанию определенные для всех сервисов
                new DictionaryCustomizer()
            };
        }
 
        public Middleware(RequestDelegate next, ISwaggerSchemaCustomizer customizer) : this(next)
        {                   
            if (customizer != null)
                m_schemaCustomizers.Add(customizer);
        }
 
        public async Task InvokeAsync(HttpContext context)
        {
            if (context.Request.Path.Value.Contains("swagger.json"))
            {
                await SwaggerSchema(context);
                return;
            }
 
            await m_next.Invoke(context);
        }
 
        private async Task SwaggerSchema(HttpContext context)
        {
            using (var memory = new MemoryStream())
            {
            var respBody = context.Response.Body;
            context.Response.Body = memory;
 
            await m_next.Invoke(context);
 
            context.Response.Body = respBody;
 
            memory.Seek(0, SeekOrigin.Begin);
            using (var reader = new StreamReader(memory))
            {
                var text = reader.ReadToEnd();
                var schema = JObject.Parse(text);
                foreach (JProperty item in schema ["components"]["schemas"])//расположение моделей может отличаться в различных версиях Swashbuckle
                {
                    //кастомизируем модели
                }
                await context.Response.WriteAsync(schema.ToString());
            }
        }
    }

И тогда подключение этого Middeware будет выглядеть следующим образом:

C#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
    public void Configure(IApplicationBuilder app, IApplicationLifetime appLifeTime, IHostingEnvironment env)
    {
        //...
        var customizer = app.ApplicationServices.GetService<ISwaggerSchemaCustomizer>();
        if(customizer == null)
            app.UseMiddleware<SwaggerCustomizeMiddleware>();
        else
            app.UseMiddleware<SwaggerCustomizeMiddleware>(customizer);
        app.UseSwagger().UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint($"/swagger/v1/swagger.json", "v1");
        });
        //...
    }

Ну а в сервисе для подключения своего кастомайзера достаточно зарегистрировать в DI контейнере экземпляр для интерфейса ISwaggerSchemaCustomizer

C#
1
2
3
4
5
6
    public override void ConfigureServices(IServiceCollection services)
    {
        //...
        services.AddSingleton<ISwaggerSchemaCustomizer>(new MyCustomizer());
        //...
    }

Надеюсь кому то поможет в решении подобных проблем

Размещено в Без категории

« Визуализация алгоритма поиска расстояния Левенштайна Главная страница

Надоела реклама? Зарегистрируйтесь и она исчезнет полностью.

Всего комментариев 0

Комментарии

Новые блоги и статьи Все статьи Все блоги /
Новый ноутбук volvo 07.12.2025 Всем привет. По скидке в "черную пятницу" взял себе новый ноутбук Lenovo ThinkBook 16 G7 на Амазоне: Ryzen 5 7533HS 64 Gb DDR5 1Tb NVMe 16" Full HD Display Win11 Pro	Музыка, написанная Искусственным Интеллектом volvo 04.12.2025 Всем привет. Некоторое время назад меня заинтересовало, что уже умеет ИИ в плане написания музыки для песен, и, собственно, исполнения этих самых песен. Стихов у нас много, уже вышли 4 книги, еще 3. . .	От async/await к виртуальным потокам в Python IndentationError 23.11.2025 Армин Ронахер поставил под сомнение async/ await. Создатель Flask заявляет: цветные функции - провал, виртуальные потоки - решение. Не threading-динозавры, а новое поколение лёгких потоков. Откат?. . .	Поиск "дружественных имён" СОМ портов Argus19 22.11.2025 Поиск "дружественных имён" СОМ портов На странице: https:/ / norseev. ru/ 2018/ 01/ 04/ comportlist_windows/ нашёл схожую тему. Там приведён код на С++, который показывает только имена СОМ портов, типа,. . .	Сколько Государство потратило денег на меня, обеспечивая инсулином. Programma_Boinc 20.11.2025 Сколько Государство потратило денег на меня, обеспечивая инсулином. Вот решила сделать интересный приблизительный подсчет, сколько государство потратило на меня денег на покупку инсулинов. . . .
Ломающие изменения в C#.NStar Alpha Etyuhibosecyu 20.11.2025 Уже можно не только тестировать, но и пользоваться C#. NStar - писать оконные приложения, содержащие надписи, кнопки, текстовые поля и даже изображения, например, моя игра "Три в ряд" написана на этом. . .	Мысли в слух kumehtar 18.11.2025 Кстати, совсем недавно имел разговор на тему медитаций с людьми. И обнаружил, что они вообще не понимают что такое медитация и зачем она нужна. Самые базовые вещи. Для них это - когда просто люди. . .	Создание Single Page Application на фреймах krapotkin 16.11.2025 Статья исключительно для начинающих. Подходы оригинальностью не блещут. В век Веб все очень привыкли к дизайну Single-Page-Application . Быстренько разберем подход "на фреймах". Мы делаем одну. . .	Фото: Daniel Greenwood kumehtar 13.11.2025	Расскажи мне о Мире, бродяга kumehtar 12.11.2025 — Расскажи мне о Мире, бродяга, Ты же видел моря и метели. Как сменялись короны и стяги, Как эпохи стрелою летели. - Этот мир — это крылья и горы, Снег и пламя, любовь и тревоги, И бескрайние. . .

Сообщение форума

Отменить изменения