В кириллических доменах и урлах ужасно одно — если попробовать расшарить (как минимум из хрома) что-то вроде https://тест.рф/тест, то получится http://xn--e1aybc.xn--p1ai/%D1%82%D0%B5%D1%81%D1%82

1. Мы используем https://github.com/Swagger2Markup (о нем писала @Lananovikova), но в git'е не заявлено поддержки OpenAPI 3.0 и в эксперементах были случаи, с которыми Swagger2Markup не справлялся. Я не вижу проблем, чтобы написать свой конвертор в Asciidoc или rst или в любой текстовый (даже нетекстовый) markup, но swagger2markup в реальных задачах пока не подводил.
2. Получаемый файл прекрасно конвертируется и в html, и в pdf. Но для pdf нужна цепочка через docbook-xsl (!!! ни в коем случае не родной конвертер). Не вдаваясь в подробности проще всего скачать https://www.asciidocfx.com/ (уродский, но вполне работающий редактро asciidoctor) и вот этими файлами https://github.com/CourseOrchestra/course-doc/tree/master/docbook-xsl-report заместить те, которые установил AsciidocFX. Кнопочка "сохранить в pdf" теперь будет делать то, что нужно
3. Обычно мы вставляем спецификацию Swagger в более общий документ (как раздел или приложение). Что, что, а это Asciidoctor делает хорошо.
4. Включение диаграмм, рисунков, чего угодно.. проблемой не является

а вот причины никто никогда не узнает

Вот знать бы точно