Как документировать поля форм (в т.ч. валидацию, логику), api, БД?

Question

[Capito]

Здравствуйте,

Начали разработку web-приложения (SPA) в сегменте enterprise. Приложение содержит кучу форм, гридов и т.п. Все эти поля связаны кучерявой логикой.
На сейчас, поля описаны в excel, API описано в Api-blueprint формате в .md файлах. БД вообще ни как не описана, но понятно, что можно сделать реверс ижениринг и посмотреть связи.

Подскажите, есть ли какой-либо софт или методология, best practices, как документируются поля форм, апи, поля БД и что бы это было все в одном месте и ссылалось друг на друга. Напр. по полу в БД найти поле в API и/или поле в форме и обратно. Опять же, четкого сопоставление нет, могут быть поля api без полей формы и поля в БД, как и обратное, т.о.
может быть, что поле в форме != поле в апи != поле в бд.
Пробовал писать просто текстом (таблицами) в ТЗ, ну, какая-то каша получается, в разных местах все это. Тяжело поддерживать, напр. когда меняется название в форме, нужно найти не забыть и найти соотв. поля в БД, АПИ и поменять их.
С описанием валидации и логики тоже, как-то все размазано получается. Возможно руки растут так :) но надеюсь, что решения есть, просто я о них не знаю.

Спасибо.

Answer 1

[xmoonlight]

Все эти поля связаны кучерявой логикой.
Возможно руки растут так

Улыбчиво)))

Идите от роли:
Роль/объект в системе (или класс) - это будет существительное => сущность в БД (товар, пользователь, статья/публикация, комментарий и т.д.).
Свойства роли (или свойства объекта класса) - это прилагательное => свойства сущности в БД (цвет, вес и т.д.).
Манипулятор (возможные действия роли/объекта; методы объекта класса) - это глагол => таблица Activity сущности в БД.

Затем - делаете обычное документирование этих классов (оно же API).

Всё, что у Вас в находится в полях форм в различные моменты времени - это частный случай взаимодействия объектов классов и/или других вспомогательных блоков.
Поэтому, каждая форма - документируется в виде перечня параметров с указанием типа поля и класса со свойством для каждого поля формы.
А вот переходы между формами - уже оформляются как схема бизнес-процесса.

Answer 2

[sim3x]

Тестами документируй
И делай максимально толстые модели

Answer 3

[Эдуард Тибет]

Вам надо:
1. Посмотреть здесь: schemaspy.sourceforge.net
2. Потом посмотреть здесь: dba.stackexchange.com/questions/515/how-do-you-doc...