Автоматическая сборка examples для Swagger NestJs

Возможно кому-нибудь понадобится этот хак, ибо я не смог найти подходящее моей проблеме решение в официальной документации Swagger.

Суть проблемы

Минимальное описание Swagger, а именно поле example, команде тестирование требовалось видить все поля запроса и его типы.

Описание полей было делать слишком сложно, некоторые запросы были собраны из смапленных данных разных entity плюс это сильно нагружала кодовую базу, Entity стало тяжело читать из-за нагруженности декораторов описания полей, валидации, а теперь и описание типов свагера.

Для меня был странным сам тот факт что я не могу прокинуть в свагер уже описанную на ts энтити или даже элементарно класс или интерфейс с типами и полями.

Наше приложение проходило множество тестировании и решение было принято взять за основу те данные, которые мы получаем с фронта и принять их за истинну того какие данные мы должны получить. И я написал такой метод сам, чтобы закрыть потребность бизнеса на текущие поля.

Никого не призываю делать ровно так же, но это может помочь тем кто точно уверен в том, что это сможет решить его проблему так же как нашу.

Реализация и сбор данных

if(process.env.DEV) {     app.use(GatherRequests); }

Для начала подключим нашу кастомную мидлвару GatherRequests . Ее задача собирать из Request данные, изменять их под тот формат, который нам нужен, после чего записывать эти данные в файл apiData.json .

export const GatherRequests = (req,res,next) => {    // сгружаем имеющиеся данные   const apiData: any = loadApiData(apiDataPath);    // преобразуем в объект   const transformedObject = transformObject(JSON.parse(JSON.stringify(req.body)));    // это метод который заменяет id url с фронта на *   // например http://localhost:3000/page/18cfb1b0-7e01-423c-a44f-d84a30c39bd1/search   // на http://localhost:3000/page/*/search   const newUrl = replaceUUIDWithId(req.url);    // Приводим данные с request в нужный нам формат   const reqData = {     url: newUrl,     method: req.method.toLowerCase(),     body: transformedObject   }    // проверяем есть ли идентичная дата в файле apiData.json, если нет то обновляем   // В файле apiData.json хранится объект Map, ключем которого служит url   const isNeededToUpdate = () => {      const challengerData:any = reqData     const apiDataItem:any =  apiData.get(reqData.url)        if(!(challengerData?.body)) {       return false     }      if(!apiData.has(reqData.url)) {       return true     }      const challengerDataKeys = Object.keys(challengerData.body)     const apiDataItemKeys:any =  Object.keys(apiDataItem.body)       return apiDataItemKeys.length < challengerDataKeys.length;   }    // Пропускаем если обновление не требуется   if (!isNeededToUpdate()) {     return next()   }    // Обновляем если данные неактуальные   apiData.set(reqData.url, reqData);   saveApiData(apiData, apiDataPath)    next(); }

Работа с самим файлом json происходит посредствам двух фунции: saveApiData и loadApiData

const saveApiData = (data, filePath) => {   fs.writeFileSync(filePath, JSON.stringify([...data]), 'utf-8'); }  export const loadApiData = (filePath: string) => {   if (fs.existsSync(filePath)) {     const fileData = fs.readFileSync(filePath, 'utf-8');     return new Map(JSON.parse(fileData));   }   return new Map(); }

Давайте еще подробнее взглянем на функцию transformObject

const transformObject = (input) => {   const transformed = {};    for (const key in input) {     if (input.hasOwnProperty(key)) {       const value = input[key];       const uuidRegex = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g;        if (typeof value === 'string') {         if(value.match(uuidRegex)) {           transformed[key] = 'id';         } else {           transformed[key] = 'string';         }       } else if (typeof value === 'number') {         transformed[key] = 1000;       } else if (typeof value === 'symbol') {         transformed[key] = 'symbol';       } else if (Array.isArray(value)) {         transformed[key] = [];       } else if (typeof value === 'object' && value !== null) {         transformed[key] = {};       } else {         transformed[key] = value;       }     }   }    return transformed; }

В этом кейсе нет ничего необычного, я не хочу светить в Swagger example реальными данными, вполне хватит понимать тип поля, поэтому я вычисляю его и подменяю на строку, если я встречаю uuid, я меняю его на строку id, чтобы тестированию было понятно что поле явно относится к id.

Пример:

{   "name": "string",   "projectId": "id",   "customInformation": {} }

Как видно из первого блока кода реализации метода GatherRequests, он работает только в Dev режиме.

Теперь мы храним все данные о реквестах всего api в файле apiData.json

Давайте теперь вернемся в то место где мы подключаем непосредственно Swagger

Работа со Swagger document

 const docOptions = new DocumentBuilder()       .setTitle('Habr')       .setDescription('The Habr API description')       .setVersion('1.0')       .addTag('Habr')       .build();   const document = SwaggerModule.createDocument(app, docOptions);

Это базовое подключение Swagger в NestJs. Но прежде чем настроить сделать настройку модуля и указать его url мы модерируем объект document напрямую, внеся туда кое-какие свои изменения

  const apiDataPath = path.join(Paths.src, 'apiData.json');   const apiData = await loadApiData(apiDataPath);  // Проходим по документу Swagger и модифицируем его поле example   Object.entries(document.paths).forEach(([url]) => {        // В GatherRequests мы подменяли id на * в url, а здесь мы приводим все в формат Swagger       // /v2/api/product/* --> /v2/api/product/{id}       const apiDataUrl = replaceBracesWithAsterisk(url)        // Если находим соответствующи урлы то модифицируем объект document       if(apiData.has(apiDataUrl)) {         const apiDataObj:any = apiData.get(apiDataUrl)         document.paths[url][apiDataObj.method].responses[200] = {           content: {             'application/json': {               example: apiDataObj.body             }           }         }       }     });    // _____________Настраиваем Swagger__________________    SwaggerModule.setup(`/api/docs`, app, document);

Заключение

Это решение не является волшебной палочкой, а является только узконаправленной задачей. Если у вас есть возможность описать сущности стандартным путем в Swagger, воспользуйтесь им.

Надеюсь вам понравилась моя статья, если она была для вас интересной или хоть как-то вам помогла, поставьте ей лайк, мне приятно видеть, что я делюсь своим опытом не зря.

Мой linkedIn