Грань между темной и светлой стороной или как работать с документацией

Сегодня я хочу поделиться своим опытом написания документации с помощью swagger при параллельной разработки backend и frontend. При этом появляются сложности у backend с поддержкой актуальной версии документации, а у frontend отслеживать что именно и где изменилось в документации. У нас было много спорных моментов, частые конфликты когда одна из платформ просила что-то изменить и не уведомляла остальные платформы. Или обычная опечатка в ответе запроса. Неверный формат данных в описании документации. Вроде бы мелочь, но при исправлении этого все ломалось. А на поиск уходило значительное время. Да все это можно решить менеджментом, но и он не всесильный. Наверняка это не только у нас. Поэтому я решил написать несколько советов, которые мы и сами используем, чтобы избежать конфликтов и трудностей.

Важность схем.

Описывать тело ответа и запроса более развернуто — создать схему. То что для backend само собой разумеется, может быть непонятно для frontend. В этом есть еще один смысл, все мы люди и все мы можем ошибаться, поэтому за основу мы берем не тело ответа, а модель которую описали в теле ответа документации. Если тело ответа запроса не соответствует описанному телу ответа мы предупреждаем backend, и не придется несколько раз переписывать клиентскую часть. Так же мы в схеме описываем все массивы констант так что их можно брать из документации.

Git для swagger

Когда модель в ходе разработки меняется, все изменения вносить в отдельный документ и уведомлять об изменениях frontend. Так мы избегаем несоответствия на разных платформах.

Переиспользования

Важное правило при написании документации — переиспользование схем. Это важно не только потому что уменьшается количество кода, но и при изменениях в одной схеме мы будем уверены что изменились и другие схемы. Например, когда схемы комбинируются. Но появляются трудности с тем чтобы описать где и что изменилось. Так что важно все схемы выносить в раздел компонентов и использовать ссылки, так проще следить за изменениями.

В заключение, возможно у вас есть какие то советы или опыт того как вы преодолевали сложности при написании документации и работе в команде, буду рад если вы поделитесь ими в комментариях.

👍НравитсяПонравилось2
В избранноеВ избранном3
LinkedIn
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Не знаю на чому у вас бекенд, але TypeScript фреймворки можуть дуже добре допомогти в цьому плані, бо статично контролюють правильність введення назв параметрів. А якщо вони ще й декоратори використовують, то синхронізацію між документацію й реальними даними можна довести до 100%.

Тобто фреймворк може брати в роботу те, що вказано в метаданих OpenAPI, і автоматично робити валідацію вхідних даних, ну і видавати автоматичні попередження, якщо відповідь сервера відрізняється від задокументованої відповіді.

А якщо щей фронтенд написано теж на TypeScript, це взагалі — пісня, бо 100% синхронізацію можна зробити ще й між фронтом і беком за допомогою розшарених моделей.

До речі, у топіку сказано, що рішенням проблем розсинхронізації є створення моделей-схем, на які можна посилатись з багатьох місць. Так, це доволі відчутне покращення, але і у назві моделі можна зробити помилку, чи перейменувати її, але це вже дрібниці, звичайно ж.

Більша проблема з описом вхідних параметрів, бо для кожної комбінації різних параметрів робити окрему модель-схему — напряжно.

Точно знаю, що NestJS працює з OpenAPI, але не знаю на скільки добре.

Ну а якщо ви не боїтесь спробувати новйо, яке ще тільки проходить обкатку, і місцями ще фарбою пахне, можете спробувати мій фреймворчик — Ditsmod.

1. Документація по роботі з OpenAPI.
2. Проста реалізація examples/openapi.
3. Клонувати, запустити, поковиряти:

git clone git@github.com:ditsmod/ditsmod.git
cd ditsmod
yarn
yarn boot
yarn start10

Ну і після цього перейти по http://localhost:8080/openapi

То на чому ж у вас бекенд і фронтенд?

nest.js? Как оно вообще? Помогает не утонуть в минималистичном гавне (express.js)?

не совсем согласен nest.js ускоряет работу и с ним легче работать но он менее расширяем и менее гибче чем express.

Тобто ви не користуєтесь фреймворком на бекенді?

в основном такой стек node.js (express.js | koa.j) но иногда используем в принципе nest.js тоже построен на фреймворке express

Подписаться на комментарии