«в Ворде, Постум! и апдейтится руками»

Как-то по приколу дискутировали с разработчиком, можно ли написать реальные ТУ в стихотворной форме. Сошлись на том, камнем преткновения станут децимальные номера и обозначения ГОСТ-ов.

Отнюдь, я с вами не согласен.
Формата есть альтернатива
Заместо расширения md
Использовать adoc
)

Ворд вообще вечен, по-моему))) у нас тут заказчики откололи - к статье в вики упрашивали добавить то же самое, но оформленное в ворде и в пдф. На предложение "нажать три точечки" и выгрузить самим в чем хотят - обиделись смертельно🤣

Кстати у меня вопрос как раз про ворд!
Памагити! Я только учусь.

У меня есть ссылка на свагер, там я вижу эндпоинты, методы, кнопочки try и execute, могу выполнять запросы и видеть ответы.
И у меня задача задокументировать наш апи в ворде.
Я слышал, что свагер каким-то образом что-то документирует, но так и не понял как.
Подскажите, где почитать!
Или может есть какая-нибудь инструкция для чайников, где описано как мне в еспд-документацию это апи засунуть? Типа делай раз, делай два.

А Ворд это обязательное требование? У вас уже есть удобная в использовании документация, а перенос в Ворд сильно уменьшит это удобство.

Если Ворд нужен формально, чтобы контракт закрыть, то я бы попробовал из странички сваггера делать Ворд с помощью pandoc, а для живых пользователей оставил бы сваггер.

Попробовал pandoc. Загрузил он в ворд только лишь названия методов, без входных и выходных параметров, т.к. они получаются через js. Немного не то, что хотелось.
Скорее всего проще руками переносить из свагера в ворд.
Все равно спасибо))

есть еще не совсем изящный способ - визуализировать сваггер через swagger-ui, а потом скриншотов навставлять в word😃

😊
хочется еще подобавлять к свагерскому тексту еще и свой - типа диапазоны значений, некие ограничения и т.п.

можно в редакторе поправить, что нужно, но только на лету https://editor.swagger.io/

А если в сваггер едиторе открыть и сгенерировать статический HTML? Его уже пандок без проблем конвертнет по идее

Как писал выше, я - новичок в свагере. Мне для этого нужно что то сделать через гид, что бы работать в свагер- едиторе ?

А PDF годится?

Да!

Сваггер - это спека для создания АПИ, точнее описания в формате, понятном вашему комплюктеру (JSON/YAML). А ваша ссылочка ведёт на swagger UI (она кстати публичная? Можете ее дать?) где ваш АПИ отображается в удобном для человеков формате (как верно заметил Николай выше - это и есть наиболее удобный способ предоставления документации на АПИ). Прелесть в том, что из этого же JSON или YAML файла генерируется и сам АПИ, поэтому дока гарантированно ему соответствует. Сваггер эдитор https://editor.swagger.io/ это онлайн редактор для работы со сваггер файлами. Вам нужно открыть в нем свой сваггер файл (File > Import), затем сгенерировать статический HTML (Generate Client > html2 наверное). Я так не делал, но мне кажется это наиболее правильный способ. Дальше уже конвертация в docx

))))

А ещё вот https://openconnectivityfoundation.github.io/swagger2doc/

Зачем Word? ЕСПД, можно к любому документу сделать приложение на диске в удобном формате, любой файл

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

Просматриваю и вот что для себя отметила:
-Есть вариант просто скопировать из документации по использованию и "портянкой" вывесить на сайт.
-Есть вариант краткого описания и по кнопке Подробнее вынести остальное текстом, таблицами, рисунками.
-Есть ещё вариант краткое описание и видео инструкции по использованию.

Ссылка конечно публичная, но только для впн🤷🏾‍♂️

Ладно уж, всем спасибо)))
Буду пробовать.
Я вот про автоматизацию спрашиваю потому что у меня этих апи (свагеров) не один и не два. И меняются они периодически. Поэтому и хочется: нажал кнопку - обновил описание системы