(Организационный вопрос) Какие есть инструменты и техники разработки API?

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

CJRoman, Значит низкий фактор ответственности у разработчиков. Нам обычного *.txt хватало для описания API.

Lander, А есть способы как с этим бороться? Возможно даже не программными методами, а более организационно? Может есть смысл нарисовать UML-диаграмму с привязкой API-методов по ним?

А есть способы как с этим бороться?

Навеяло... Из дневника начальника: сегодня попробовал метод "кнута и пряника", понравилось! Но, пряником бить не удобно, завтра попробую метод "кнута и кнута"...

В нашей работе подобного плана нам хватало:
а) Вики (прямо в репозитории с кодом)
б) Версионирования
в) Заранее определенного плана, что должно делать API (иными словами мы никогда не бросались делать то, что должно делать "непонятно что") :)))

Назначьте ответственного за ведение соотв. документации, swagger'а или текстового файла как озвучил коллега выше.

> Используется. Не помогает. Вовремя не ведется, либо все равно мы получаем совсем не то, чего ожидается

Ну что тогда сказать... - наверное дело не в инструментах

CJRoman, Не были бы это программисты, можно было бы какой то KPI придумать. С программистами, наверное всё таки лучше аргументировано объяснить что это не тупое исполнилово, а что это на самом деле важно. Донесите мысль что 10 минут, потраченных на актуализацию документации сэкономят часы разборок и выяснений кто виноват.

CJRoman какими языками пользуетесь для бэка/фронта?

Можно попытаться бороться путём настройки билда проектов таким образом, что интерфейсы перегенериваются каждый раз по описанию API. Этого сложно добиться, но если у вас действительно стоит такая проблема, возможно стоит попытаться реализовать такое подход.

Конечно, тут желательны языки со статической типизацией вроде C#/TypeScript, желательно чтобы для них были библиотеки-генераторы.

Станислав Макаров, бэк - Ruby on Rails, фронт - JS/Vue.js

CJRoman тогда вариант отпадает) Разве что вы найдёте/сделаете сами генератор простых тестов, который дёргает методы рельсового контроллера и проверяет, что они возвращают адекватный ответ.

CJRoman а можно чуть подробнее вы используете swagger, добавляете новые методы но при этом не пишете ApiDocumentation и не подерживаете в актуальном состоянии?
*так выходит из вашего ответа

тут проблема слегка не техническая: а скорее организационная.
для решения :
1 заставить писать ApiDocumentation и поддерживать в актуальном состоянии. (+0.5 - 1 ч к работе над задачей)
2 заставить писать тесты, покрытие 90и более % для api очень желательно
3 пинать менеджера проекта (этож не Вы?) чтобы вёл актуальную документацию

Сами пишем в похожем стеэке : ROR + Angular/Ember/React - запрос к /api/documentation выгружает json c swagger определением :
{"swagger":"2.0","info":{"version":"1.0","title":"Satyr","description":"Service for.....", "termsOfService" .... }

Фронт/мобил залез глянул что изменилось - поправил.

А вот если Бэк раздолбаи - то тут пара пятничных/понедельничных совещаний с мозгопромывкой, что до сихпорт не отдал Апи фронту помогут_) или Вам придётся искать нового бэка ))

В том-то и дело, что технически проблема не стоит) Мы тоже используем grape и swagger для API.
В том-то и прикол, что не все держат в актуальном состоянии это.
Вот я и ищу способы организационного решения данной проблемы)

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

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

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