в итоге на выходе я теперь получаю html вместо swagger. И в MkDocs этот html довольно симпатично отображается

swagger2markup не поддерживает Open API 3. Мы пользуемся вот этим проектом https://github.com/openapi-contrib/openapi3-generator

markup там какой-то дурной, но тоже довольно просто доработать

а asciidoc-шаблон я наш вкачал

а кто-нибудь встраивал сваггер в статику с md?  я что-то вообще не оченб в этом шарю

А в pdf? Поддержка 3.0 ест, но в качестве эксперимента

Ну специально pdf не делали. Но можно сохранить html в pdf))

Я так понял yaml генерит в маркдовн. Как на выходе получается?
И что еще нужно ,помимо самого OpenAPI 3 Generator и npm?

скорее в asciidoc, маркдаун там плохой шаблон, но можно легко сделать свой (в качестве шаблонизатора используется handlebars.js). На выходе имеем asciidoc, причем размеченный тэгами. Т.е. в конечную документацию я могу вставлять не сгенерированные файлы а то из них, что нужно. А дальше — html... pdf... jekyll...  все. что душе угодно. Нужны только npm и OpenAPI 3 Generator

вот тут советовали hugo — спасибо.

Мы сейчас наш сайт (flussonic.ru ) меняем на hugo.

Я задолбался от бесконечных CMS с необходимостью их обслуживать, бекапить.

И мы проработали интеграцию автосборки документации в сайт на hugo, вышло очень прилично

а spring нет желания попробовать?

обычный контрдовод относительно SSG такой: поддерживать сайт на CMS-ке сможет любой контент-менеджер без глубокого айтишного бэкграунда, а для SSG нужно и в гит уметь, и в верстку чуть-чуть

как вы это решили?

> поддерживать сайт на CMS-ке сможет любой контент-менеджер без

по факту это не так. Такому менеджеру рядом нужен ещё девелопер, который сбекапит мускль, поправит настройки.

Я попробовал двум неглупым менеджерам доверить сделать свой сайт. Они развернули виртуалку, туда что-то поставили. Через 3 часа хетцнер блокирнул эту виртуалку и прислал мне письмо, что ещё один такой рассадник спама и он блокирнет весь мой аккаунт.

Т.е. менеджер не может поставить CMS на PHP и не открыть там три дыры для рассылки спама.

Я не хочу держать отдельного технаря для обслуживания сайта, я уже пробовал. Это больно, дорого, бестолково на наших объёмах. У нас в b2b сайт — это просто витрина, пара няшных лендингов.

Плюс менеджер абсолютно не в состоянии делать бекапы и проверять их работоспособность, а сайт на PHP требует этого _постоянно_

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

Что касается «не может в гит», то в целом гитлаб с его веб-IDE здорово помогает.

Но это я всё не отвечаю на твой вопрос.

Отвечая на него: у меня сайт правит менеджер сайта (по сути он больше про SEO) и техпис. Оба могут что-то пойти сделать или хотя бы внятно сказать «ой, у нас всё сломалось, помогите».

нет, потому что я не знаю что это такое и мы только что переехали на Hugo =)

Но вот самописный шмоток кода на рубях, который берет маркдаун, транслирует в нём ссылки, втыкает includesection, валидирует ссылки и т.п. хочется выбросить конечно =)

о, знакомые боли

у нас лендинг (documentat.io) тоже на SSG и хостится на GitHub Pages, именно чтобы не было мороки с базами, nginx-ом, уязвимостями, бэкапами и тормозящими виртуалками

из минусов — отвратительно старый SSG (middlemanapp.com, привет из моего прошлого на Ruby) и плохая поддержка HTTPS на GitHub Pages

раньше еще некоторые российские провайдеры блочили айпишники GitHub Pages, но вроде всех попустило уже

я себе вижу это так, что SSG можно переложить куда угодно, включая виртуалку с nginx за 15 минут

ну час

это так, с оговоркой о том, что это усложнит конфигурацию. Нужно развернуть виртуалку, захарденить ее, настроить nginx, всё протестить.

Думаем переехать на аналог S3 в Яндекс.Облаке, чтобы был тупо статический хостинг.

А Netlify вы не рассматриваете для деплоя? Я уже пробовал GitHub Pages, GitLab Pages. Мне больше всего понравился Netlify. Я ещё не пробовал S3.