на xc7.ru был пост про контент для соцсетей. у нас в проде другая история - мы пишем API для внутреннего сервиса. и если документация кривая, никакой контент не спасёт.
раньше у нас было так: висит /api/v1/orders, фронтендёр тыкает - получает 500. я лезу в логи, вижу null pointer exception. оказывается, кто-то забыл добавить проверку на пустой массив.
и так каждый спринт. код ревью проходит, тесты зелёные, а на стейджинге всё падает.
мы сделали три вещи:
openapi.yaml лежит в репе, не расходится с кодом. если в yaml поле required, то в go структуре тоже requiredspectral на CI. любое несоответствие валится в билдспустя пару месяцев количество инцидентов упало раза в три. фронтендёры перестали писать в чат "а почему у вас тут 500?". я перестал лазать по логам каждые полчаса.
документация - это не скучная бумажка. это способ не тратить время на однотипные баги.
если пишете API - держите контракты в коде. проверено на продакшене.
качественный контент для разработчика - это когда код и документация живут вместе. а не когда один пишет swagger, а второй героически его игнорирует.
--- API, документация, Go, опытКомментариев пока нет