TypeScript моделі для Open API Specification v3.1.0

Підписуйтеся на Telegram-канал «DOU #tech», щоб не пропустити нові технічні статті

Щоб використовувати моделі Open API Specification v3.1.0, необхідний TypeScript v4.1+, через Template Literal Types.

Встановлення:

npm i @ts-stack/openapi-spec

Репозиторій із @ts-stack/openapi-spec

Давним-давно вже існують аналогічні моделі для OAS, але почавши ними користуватись, побачив хаки із типом any у визначенні моделей, що нівелюють TypeScript фічі, ради чого і були створені ці моделі. Чого тільки вартий хак із PathsObject, що по-суті перекреслює дві третини усіх TypeScript моделей цієї бібліотеки. І це при тому, що дану бібліотеку скачують більше, ніж 300 тис. разів на тиждень, і використовують її такі відомі компанії як loopback.

Хоча автор цієї бібліотеки даний хак описує як:

Hack for allowing ISpecificationExtension

але думаю можна легко обійтись без нього і все-таки використовувати Specification Extensions.

Як це реалізовано в мене:

import { OasObject, SpecificationExtensions } from '@ts-stack/openapi-spec';

type ExtendedOasObject = OasObject & SpecificationExtensions<'x-one' | 'x-two'>;

const extendedOasObject: ExtendedOasObject = {
  info: {title: '', version: ''},
  openapi: '',
  'x-one': '',
  'x-two': '',
};

Окрім кращого визначення TypeScript моделей, у мене додано документацію до усіх моделей та усіх їхніх властивостей.