Comments 4
Проблема осложнялась тем, что наш партнер разрабатывал на 1С, и во всех современных спецификациях для него были слишком сложно освоиться, поэтому встала задача предоставить документацию в человекориентированном виде - DOC, PDF и прочее.
У Swagger есть UI чем он не подошёл? За весь мой опыт, этого всегда хватало...
Ок не подошёл UI, так вроде вы выгружаете в html, зачем pdf?
О да, это всеобщая боль... В итоге лично я пришел к может и неправильному, но по сути верному опыту - если заказчик не понимает формат OpenAPI 3.0, не хочет его открыть в UI - то это не наши проблемы, а его. Пусть ищет тех, кто разберется. Для особо важных - даем пример клиента на Python.
Такой подход может привести, что заказчик больше не захочет сотрудничать с Вашей компаний, ну и как итог Вашей команде разработке придется искать новое место работы. Очень часто сталкивался с таким подходом в работе - скидывание проблем на других, он ни к чему хорошему не приводит. Если заказчик Ваш клиент, и платит Вам деньги - нужно демонстрировать клиентоориентированный подход и работать на результат, зачастую выходя за рамки должностной инструкции
Зачетно, конечно. Но зачем эту логику имплементировать в каждом сервисе? Если придётся какой-то сервис переписать на другой язык (Go?), то это разобьёт вашу стройную схему.
Да и, обычно, спецификации на API выдаются не поштучно, а сразу пачкой. Плюс есть еще проблемы версионирования, API бывает публичное и приватное, и т.д.
На своих проектах мы просто публикуем все публичные API отдельно, публикация этих API автоматическая после прохождения QA тестов и фиксации релиза.
Отдел взаимодействия с клиентами берёт эти спецификации и их уже предоставляет Заказчикам. Если появляется какой-то заказчик, который готов заплатить за PDF/DOC/TeX - то это уже не головная боль разработчика.
Это даёт нужную гибкость командам (не завязаны на конкретный язык/фреймворк, могут примерять как Contract First подход, так и Code First - тут всё на откуп Архитекторам), не завязаны на хотелки Заказчика (а теперь тоже самое, но с перламутровыми пуговками).
Команда разработки не тратит своё дорогое время на это.
Генерация PDF-документации из OpenAPI-спецификации в SpringBoot-приложении