NSwag vs Swashbuckle for Swagger, Typescript client API generation, and fighting undefined/nulls in DTO

I have already expressed my love with Swagger :) Over time, however, I met Swagger’s sister — NSwag — and fell in love with her even more :)

Long story short, NSwag doesn’t have an IFormFile issues I was solving in Swagger out of the box. But the reason I moved is actually a bit different. We wanted to use OpenAPI definitions for autogenerating clients for our API. Writing something like this:

export interface IFirmwareInfoDto {
    exists: boolean;
    versionString: string;
    releaseDate: string;
    deviceGeneration: DeviceGeneration;

async getAvailableFiles(options?: AxiosRequestConfig): Promise<IFirmwareInfoDto[]> {
    const response = await axios.get<IFirmwareInfoDto[]>(
        {...defaultOpts, ...options},
    return response.data;

by hand for every API action is not only tedious, but also error prone. Thank goodness, there are tools for automatic generation of those based on OpenAPI definitions. We used OpenAPI Generator initially (since Swashbuckle doesn’t have anything built-in), and it was good, but, as usual, devil was in the details. And the devil here was C# enum handling.

Actually, OpenAPI Generator had no issues with handling enum. It just doesn’t handle them at all :) There were just two options, both of which were affecting API itself: we could either express enum elements as string or as number. That was suboptimal. So, having a C# DTO and Action like this:

public class UserDto
	public string Name { get; set; }
	public DateTime BirthDate { get; set; }
	public Sex Sex { get; set; }

public UserDto Get(int id)
	return new UserDto()
		Name = "Artur",
		BirthDate = new DateTime(1985, 5, 12),
		Sex = Sex.Male,

We got the following Dto generated in Typescript

export interface UserDto {
    name?: string | null;
    birthDate?: Date;
    sex?: Sex;

export enum Sex {
    NUMBER_0 = 0,
    NUMBER_1 = 1

We could get Sex enum generated like this:

export enum Sex {
    Male = 'Male',
    Female = 'Female'

But only if we configure our API to behave the same way (i.e. you would receive the following JSON as a result of an http call

  'name': 'Artur',
  'birthDate': '2009-02-15T00:00:00Z',
  'sex': 'Male'

It’s a debatable topic, whether to use strings or ints for enums in the API, but in some cases (like Flags enums, where several values could be combined) ints are unavoidable.

So, we tried NSwag and thankfully, here’s what we have with it:

export enum Sex {
    Male = 0,
    Female = 1,

The key difference, is that NSwag has it’s own client generator, and it takes into account some of extensions that NSwag adds when generating API definition (i.e. string representation of enum values are stored in description fields).

Of course, NSwag also generates nice little (well, not so little :)) typescript client as well:

export class UserClient {
    constructor(baseUrl?: string, instance?: AxiosInstance) {
      // ...

    get(id: number): Promise<UserDto> {
      // ...

…and we have lived happily ever after with NSwag, unless we discovered another glitch. It’s called undefined. If we take a closer look at UserDto we could notice, that all properties are undefinable (this little ? sign next to the property name):

export interface IUserDto {
    name?: string | undefined;
    birthDate?: Date;
    sex?: Sex;

It’s not only inconvenient (because in typescript you would always have to check, if the value is really defined or not), but it’s also just wrong, because with aforementioned c# definition both birthDate and sex will always be defined.

Luckily, this could be fixed rather easy. We have introduced a special RequireValueTypesSchemaProcessor, that you could integrate into NSwag with oneliner:

options.SchemaProcessors.Add(new RequireValueTypesSchemaProcessor());

and DTOs will be automatically fixed for you:

export interface IUserDto {
    name: string;
    birthDate: Date;
    sex: Sex;

Go take a look at the sources if you want more details! You will also receive a bonus — the way to easily get back to generating undefinable for some DTOs where you particularly want that (e.g. for HTTP PATCH requests) :)

As usual, you could get complete C# project along with all generated client examples from github. Check out clients folder for already generated clients, or run yarn nswag-client or yarn swashbuckle-nswag-client to regenerate them.

OAuth в SPA или неожиданные сложности интеграции логина через соцсети в React с Asp.Net Core

Это история про то, как казалось бы типичная задача интеграции входа через соц.сети в React/Asp.Net Core приложении может превратиться в длинную сагу и закончиться open-source библиотекой :)

Если читать лень, то можно сразу пойти на гитхаб, где и посмотреть весёлую гифку и прочую документацию по интеграции и использованию, ну а здесь я расскажу чуть подробнее :)

В Asp.Net Core существует замечательная встроенная интеграция с внешними провайдерами аутентификации (OAuth/OpenId и прочее нестандартное), а также сторонние плагины, поддерживающие аутентификацию даже через VK. Однако весь этот механизм подразумевает, что у вас обычное server-side приложение (с forms-авторизацией), и никаких собственных access_token’ов, которые привычны в SPA вам генерироваться не будет.

Вот вот мне и загорелось желание воспользоваться всем этим огромным количеством готовых решений и подружить его с SPA. Как схема работы должна выглядеть в идеале? Согласно AuthCode Flow (который считается рекомендуемым для использования в SPA), это должно выглядеть примерно так:

SPA получает AuthCode у стороннего провайдера и передает его на бэкэнд приложения. Бэкэнд проверяет верность кода, ищет этого пользователя в своей БД (и создает, если требуется) и возвращает на фронтенд access_token, с которым и происходят все дальнейшие запросы.

Для первого шага (получения AuthCode) в SPA существуют готовые реализации в виде, например, реакт-компонентов. Но под каждого OAuth-провайдера они разные, и подбор и настройка могут отнять достаточно много времени. После интеграции написанной библиотеки IdentityOAuthSpaExtensions (и настройки бэкэнд-части согласно инструкциям от майкрософта), запрос AuthCode из SPA будет состоять из двух частей:

  1. Создание обработчиков и подписка на события:
  2.     window.addEventListener("message", this.oAuthCodeReceived, false);
        function oAuthCodeReceived(message) {
            if (message.data && message.data.type === 'oauth-result') {
                if (data.code) {
                    externalAuthSuccess(data.provider, data.code);
                } else {
                    externalAuthError(data.provider, data.error, data.errorDescription);
        function externalAuthSuccess(provider, code) {
            alert(`Provider: ${provider}, code: ${code}`);
        function externalAuthError(provider, error, errorDescription) {
              alert(`Provider: ${provider}, error: ${error}, ${errorDescription}`);
  3. Старт процедуры авторизации:
   window.open(`${window.location.protocol}//${window.location.hostname}:${window.location.port}/external-auth/challenge?provider=${provider}`, undefined, 'toolbar=no,menubar=no,directories=no,status=no,width=800,height=600');

В результате этого ваше SPA получит AuthCode стороннего провайдера. В дальнейшем с ним можно делать что угодно ( :)), но в нашем случае, мы хотим получить access_token от нашего бэкэнда, чтобы в дальнейшем все http вызовы совершать с этим access_token’ом. Для этого в библиотеке существует возможность проверки AuthCode («), а также (рекомендуемая) интеграция с IdentityServer в виде extension grant’a. Описание интеграции очень подробно описано на гитхабе

Итоговая схема выглядит как-то так:

Из основных плюсов библиотеки:

  1. Единая точка входа и общий интерфейс интеграции любых Auth-провайдеров (не нужно менять SPA, меняется лишь одна переменная — имя провайдера — при открытии URL авторизации)
  2. Использование стороннего кода для взаимодействия с OAuth (саму библиотеку не придется обновлять, если в сторонних OAuth что-то изменится).
  3. Добавление новых провайдеров происходит стандартным способом (по инструкции для server-side приложений) и не требует модификации самой библиотеки

Пользуйтесь, задавайте вопросы и рассказывайте об успешных сценариях внедрения!

Доклад про WebAssembly на Городе IT

10 сентября выступил на секции Enterprise конференции Город IT с докладом по WebAssembly.
С моей точки зрения, WebAssembly — это очень перспективное направление, хоть и не готовое к продакшену прямо сейчас. Но нам — разработчикам — просто необходимо внимательно следить за технологиями, которые уже в ближайшее время могут радикально изменить ситуацию в мире фронтэнда.
В докладе рассказывал про появление и развитие WebAssembly, языки и фреймворки, которые его используют, и показал возможности применения Майкрософтоской библиотеки Blazor для разработки SPA с использованием любых существующих .net библиотек (netstandard).
Спасибо всем участникам конференции за интерес и плодотворную дискуссию!

Презентация — уже сегодня на Slideshare, надеюсь на скорое появление видео (ждём организаторов!)

OpenApiGenerator: fixing multiple file upload for JS clients

Remember, I love swagger! And since we have it anyway, it’s kinda dumb to write requests to that API manually.
Why would anyone want to come up with something like axios.get(‘/user/123/payments?fromDate=2018-01-01’) without intellisense, type-checking and compile-time verifications? What if someday you change that API’s route?

OpenApiGenerator is a great solution to this. You could easily get typed-clients for your API in almost any language, and make requests as easy as UserApi.get(123, dateFrom).
But that’s a well-known thing, let’s get to the point of this article :)
OpenApiGenerator plays well with almost anything, but file arrays. File arrays were introduced to OpenApi recently, so not all the tools support them yet.
So, let’s say you have a backend method that accepts an array of files (files will be passed with the same name):

public IActionResult UploadFiles(IFormFile[] files)

OpenApiGenerator will provide you with a proper JS method, but it won’t work and will generate something like:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIk1aWkovTmf7LSJX

Content-Disposition: form-data; name="files"

[object File],[object File]

Of course, that isn’t what we want. However, it’s quite easy to monkey-patch the generated ApiClient to achieve what we want. I know monkey-patching is dirty and you should probably fix this with inheritance&overriding, but I’ll leave this to you :) So, here’s the patch:

//this is to make ApiClient correctly handle array of files
const oldBuildCollectionParam = ApiClient.instance.buildCollectionParam;
ApiClient.instance.buildCollectionParam = function(param, collectionFormat) {
    if (param == null) {
        return null;
    if (param.length > 0) {
        if (param[0] instanceof File) {
            return param;
    return oldBuildCollectionParam.call(this, param, collectionFormat);

Using Mini-Profiler with Angular and HttpClient

Performance is essential for every web app, so profiling is a must. And there’s no better tool to monitor and profile your web app than Mini-Profiler from StackExchange. It’s simple, easily integratable and provides the most important profile metrics such as request duration and SQL queries.

Our typical Web SPA setup in Rubius is based on ASP.Net Core backend and Angular frontend. So we started integrating MiniProfiler into the stack, but it wasn’t that straightforward.

The thing is, MiniProfiler works perfectly with classic pages and jquery ajax calls, but fails to display any information on Angular http requests, which makes it barely usable in SPA.
To overcome it, there is a perfect post from Georg Dangl on how to make Mini-Profiler work with Angular if you’re using HttpModule, so go read Georg’s post and gist, it’s for you :)

However, in 4.3 Angular introduced HttpClientModule as a new way to talk to the backend API (replacing old HttpModule) and once we started to migrate to it we had the same issue again. There were no information about ajax requests.
So, I sat down and ported Georg’s gist to an HttpClient. So if you care about your performance and SQL queries, go grab it!

Семинар по ASP.Net Core в Точке Кипения

14 декабря вместе с коллегой Антоном Финько выступали в Точке Кипения с семинаром по ASP.Net Core.

Очень понравилась сама площадка — Точка Кипения — это отличное место, просторный зал, огромный экран и все пришедшие 60 человек там отлично разместились (и даже если было бы вдвое больше — всё равно всем было бы удобно :)). Фотографии не передадут всего комфрота и уюта (и кофе-брейка с плюшками), но покажут, насколько было хорошо:



Это было первое IT-мероприятие в Точке, и я считаю, оно прошло отлично! Небольшой 40-минутный доклад про теоретические основы и большой практический опыт, и более чем получасовая дискуссия после. Очень порадовал обмен мнениями и опытом использования от многих присутствовавших.

Ну а тем, кто не пришел — видео и презентация ниже :)


До встречи на следующих семинарах!

Entity Framework Core и GroupBy

В новом проекте ударились во все тяжкие и используем всякие эти ASP.Net Core и Entity Framework Core.
От нового MVC впечатления исключительно положительные, от нового EF — откровенно смешанные :)

Список missing features в EF очень велик, из базового: нет GroupBy, Lazy-loading (хотя может, это и к лучшему :)), а главное, некоторые запросы, которые в EF6 спокойно выполнились бы в SQL имеют обыкновение выполняться в памяти, приводя к классическому SELECT N+1 причем прямо внутри запроса.

Отсутствие GroupBy заставило гуглить альтернативные подходы, и довольно быстро нашелся EFSqlTranslator. Если кратко, он парсит linq, сгенерированный на EF-сущностях, генерирует SQL и отправляет его через Dapper в базу (используя соединение от EF). То есть такой read-only Entity Framework :)
Поддерживает Join, GroupBy, аггрегаты, и много всего такого. При этом на удивление, не поддерживал:

      Несколько запросов подряд через один EF контекст
      Булевские типы и DateTime context.Messages.Where(x => x.IsDeleted)
      Булевские предикаты в .Any(x => x.IsDeleted) и .Count(x => x.IsDeleted)
      Join по агррегатным функциям
      Запросы с использованием переменных var deleted = true; context.Messages.Where(x => x.IsDeleted == deleted)

В общем, проект с на удивление мощным linq-парсером, при этом на удивление сырой :)
За последнюю неделю от меня в него улетело около десятка пулл-реквестов, которые экстремально быстро оказались в мастере. Теперь используем и радуемся :) Как можно EFCore использовать без него — просто не представляю.

Доклад о веб-компонентах и Polymer

Сегодня отметился докладом на томском локальном митапе фронтэнд разработчиков TomskJS.
Рассказывал про веб-компоненты и Polymer. Презентацию смотреть на Слайдшаре

или скачивать по ссылке.


Polymer и NotifyPropertyChanged в JavaScript

Есть замечательный фреймворк построения веб-приложений — Polymer. Это даже скорее не фреймворк, а реализация идеологии WebComponents в современных реалиях веб-браузеров.

Если кратко, то с его помощью можно реализовывать полноценный, удобный и быстрый (как с точки зрения производительности решения, так и скорости разработки) MVVM в JavaScript:

<dom-module id="my-component">
    <h4>ToDo list for {{name}}:</h4>
      <template is="dom-repeat" items="{{model.todoitems}}">
    <button title="ChangeName" on-tap="ChangeName"></button>
  is: 'my-component',
  name: 'Artur',
  model: {
    items: [
      {title: '1'}
  ChangeName: function() {
    this.model.name = this.name + "_1";

В WPF мы привыкли, что интерфейс перерисовывается автоматически, при изменении значения свойства: this.name = ‘New Name’;. Однако у многих js-mvvm-фреймворков, присвоения приходится производить с помощью магических функций: this.set(‘name’, this.name + «_1»). В Polymer успешно работает первый (удобный :)) вариант, однако при работе с массивами и вложенными объектами эти прелести заканчиваются. Код добавления новых элементов в список ToDo выглядит примерно так:

Add: function() {
  this.push('items', {title: 'another item'});

Редактирование же элементов в списке (например, изменение title) будет еще более ужасным:

  this.set('items.1.title', 'new title!');

Continue reading

Только React.js, только хардкор (aka долой Angular и Knockout)!

Последние годы только ленивый не писал о javascript-фреймворках. AngularJS/KnockoutJS/Backbone/Ember — выбирай на вкус :) Но, озадачившись выбором фреймворка для небольшого веб-приложения с год назад, оказалось, что серебряной пули в мире js все еще не придумали.
Backbone и Ember слишком низкоуровневы и многословны, Knockout расстраивает постоянными конвертациями данных в observable, AngularJS.. да, почему бы не попробовать Angular, подумал я тогда. Энгуляр обладал приятным синтаксисом, структура Контроллеров была более менее близка и понятна и всё шло хорошо, пока.. пока мы не уперлись в довольно стандартную для Angular проблему произодительности.
Continue reading