💬 Всем привет!
Я уже затрагивал тему OpenAPI и документирования интеграций, но снова и снова сталкиваюсь с одними и теми же проблемами. Узнайте знакомые ситуации:
🔹 "Опять из этой 1С что-то непонятное прилетает."
🔹 "Отправил им сгенерированный JSON, но они пока не ответили, правильный он или нет. Жду неделю, у них разработчик в отпуске."
🔹 "Вы не присылаете обязательные свойства в интеграционном пакете!"
🔹 "В документации одно, а в коде таких свойств вообще нет!"
...и этот список можно продолжать бесконечно.
Это всё следствие разрыва между контрактом (документацией) и реальностью.
🧐 Как это происходит?
Сегодня аналитики согласовали красивую схему интеграции, подписали её, ударили по рукам и передали на реализацию.
Завтра в процессе разработки выяснилось, что чего-то не хватает, и это просто добавили в код. Документацию обновить решили "потом", потому что у нас agile: "результат важнее документации... вот это вот все..."
И всё… Документация больше никогда не будет актуальной, потому что она никак не связана с интеграцией и не участвует в процессе.
💡 Как решить проблему?
Добавить обязательную валидацию интеграционных пакетов по спецификации!
Это решит сразу несколько задач:
1️⃣ Контракт станет максимально проработанным, ведь он напрямую влияет на отправляемые сообщения.
2️⃣ Документация всегда будет актуальной.
3️⃣ Разработчики смогут мгновенно узнать, соответствует ли их пакет требованиям, без недель ожидания.
🛠 Для удобства я написал библиотеку валидации для 1С.
Просто передайте пакет в метод — на выходе получите массив ошибок валидации.
📌 Библиотека доступна на GitHub
📖 Также можно почитать статью на Инфостарте!
👉 Делитесь опытом и внедряйте! 🔥
Я уже затрагивал тему OpenAPI и документирования интеграций, но снова и снова сталкиваюсь с одними и теми же проблемами. Узнайте знакомые ситуации:
🔹 "Опять из этой 1С что-то непонятное прилетает."
🔹 "Отправил им сгенерированный JSON, но они пока не ответили, правильный он или нет. Жду неделю, у них разработчик в отпуске."
🔹 "Вы не присылаете обязательные свойства в интеграционном пакете!"
🔹 "В документации одно, а в коде таких свойств вообще нет!"
...и этот список можно продолжать бесконечно.
Это всё следствие разрыва между контрактом (документацией) и реальностью.
🧐 Как это происходит?
Сегодня аналитики согласовали красивую схему интеграции, подписали её, ударили по рукам и передали на реализацию.
Завтра в процессе разработки выяснилось, что чего-то не хватает, и это просто добавили в код. Документацию обновить решили "потом", потому что у нас agile: "результат важнее документации... вот это вот все..."
И всё… Документация больше никогда не будет актуальной, потому что она никак не связана с интеграцией и не участвует в процессе.
💡 Как решить проблему?
Добавить обязательную валидацию интеграционных пакетов по спецификации!
Это решит сразу несколько задач:
1️⃣ Контракт станет максимально проработанным, ведь он напрямую влияет на отправляемые сообщения.
2️⃣ Документация всегда будет актуальной.
3️⃣ Разработчики смогут мгновенно узнать, соответствует ли их пакет требованиям, без недель ожидания.
🛠 Для удобства я написал библиотеку валидации для 1С.
Просто передайте пакет в метод — на выходе получите массив ошибок валидации.
📌 Библиотека доступна на GitHub
📖 Также можно почитать статью на Инфостарте!
👉 Делитесь опытом и внедряйте! 🔥