Форум программистов, компьютерный форум, киберфорум
Toros1992
Войти
Регистрация
Восстановить пароль
Оценить эту запись

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

Запись от Toros1992 размещена 07.06.2020 в 12:54
Обновил(-а) Toros1992 07.06.2020 в 13:03

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

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

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

Для нашей команды таким ограничением стала невозможность глубокой кастомизации схем отдельных DTO, используемых в API.
Пара конкретных примеров:
  1. Описание Enum.
    Дело в том, что в Swagger можно отображать допустимый набор значений Enum либо как массив чисел, либо как массив имен.
    Проблему решило бы наличие комментария к типу перечисления.
    Но, несмотря на то, что в Swashbuckle есть атрибут SwaggerSchema, который позволяет добавлять поля к схеме типа (описание, флаг readonly и т.д.), этот атрибут запрещен для применения к Enum.
  2. Отображение 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());
        //...
    }
Надеюсь кому то поможет в решении подобных проблем
Размещено в Без категории
Просмотров 187 Комментарии 0
Всего комментариев 0
Комментарии
 
КиберФорум - форум программистов, компьютерный форум, программирование
Powered by vBulletin® Version 3.8.9
Copyright ©2000 - 2020, vBulletin Solutions, Inc.