ML
Коллеги, а у кого организована публикация схем и документации на апи вашего сервиса/продукта?
Size: a a a
2020 December 05
ML
Коллеги, а у кого организована публикация схем и документации на апи вашего сервиса/продукта?
Какие вообще здесь есть практики?
Мы вот начали публиковать схему нашего конфига (json) и тут целая масса вопросов
Мы вот начали публиковать схему нашего конфига (json) и тут целая масса вопросов
AK
опен апи же (в девичестве сваггер)
AK
https://developer.rbk.money/api/ билдится дока из закрытого репозитория со схемой, веркер в виде CI собирает это в такой репозиторий https://github.com/rbkmoney/api-v2/tree/gh-pages
AK
да, также очень рекомендую ReDoc для рендера спеки, мы весь рынок прошерстили, это лучшее что есть
ML
Ага, ясно, посмотрю на redoc
ML
А человеческая документация хранится в коде, или в другом месте? Если в другом, то как мержится со спекой?
ML
Или вопрос непонятен
PK
А человеческая документация хранится в коде, или в другом месте? Если в другом, то как мержится со спекой?
лично у нас сейчас в конфлюенсе, но это дикая боль и мы в процессе переноса её в репозиторий с кодом и последующим экспортом (обратно в конфлюенс) при сборке мастера
AK
А человеческая документация хранится в коде, или в другом месте? Если в другом, то как мержится со спекой?
смотри, все идет от спеки, она может быть как жсоне, так в ямле
выглядит так https://developer.rbk.money/api/swagger.json
на эту спеку натравливаешь редок и он рендерит вот такую трехколоночную интерактивную доку https://developer.rbk.money/api/
2 нюанса
1) человеческое описание теги с подробным описанием - это специфично только для редока и их надо писать руками, см скрин
2) примеры кода специфичны для редока и их надо писать руками
в остальном все идеально работает
выглядит так https://developer.rbk.money/api/swagger.json
на эту спеку натравливаешь редок и он рендерит вот такую трехколоночную интерактивную доку https://developer.rbk.money/api/
2 нюанса
1) человеческое описание теги с подробным описанием - это специфично только для редока и их надо писать руками, см скрин
2) примеры кода специфичны для редока и их надо писать руками
в остальном все идеально работает
AK
но это только заголовки, то есть типа вот этого
остальное все автоматом со спеки берется
остальное все автоматом со спеки берется
ML
смотри, все идет от спеки, она может быть как жсоне, так в ямле
выглядит так https://developer.rbk.money/api/swagger.json
на эту спеку натравливаешь редок и он рендерит вот такую трехколоночную интерактивную доку https://developer.rbk.money/api/
2 нюанса
1) человеческое описание теги с подробным описанием - это специфично только для редока и их надо писать руками, см скрин
2) примеры кода специфичны для редока и их надо писать руками
в остальном все идеально работает
выглядит так https://developer.rbk.money/api/swagger.json
на эту спеку натравливаешь редок и он рендерит вот такую трехколоночную интерактивную доку https://developer.rbk.money/api/
2 нюанса
1) человеческое описание теги с подробным описанием - это специфично только для редока и их надо писать руками, см скрин
2) примеры кода специфичны для редока и их надо писать руками
в остальном все идеально работает
У вас только русский в описании?
ML
лично у нас сейчас в конфлюенсе, но это дикая боль и мы в процессе переноса её в репозиторий с кодом и последующим экспортом (обратно в конфлюенс) при сборке мастера
Не, вики я давно на мороз выставил вслед за гуглодоками и виндовыми программулечками
AK
У вас только русский в описании?
да, для отдельного языка отдельная спека (по крайней мере я на момент запуска проекта про локализацию ничего не нашел)
AK
кстати из плюсов есть автоматизированное создание чейнджлога, что сильно облегчает
ML
да, для отдельного языка отдельная спека (по крайней мере я на момент запуска проекта про локализацию ничего не нашел)
У меня специфика (стал бы я спрашивать, если бы ее не было): у меня фактически два метода, в которые засовывается жсон, спека которого около 4 тыс строк (конфиг).
Плюс техписы не имеют доступа в исходники софта
Плюс техписы не имеют доступа в исходники софта
ML
Оу, чудесно!
AK
У меня специфика (стал бы я спрашивать, если бы ее не было): у меня фактически два метода, в которые засовывается жсон, спека которого около 4 тыс строк (конфиг).
Плюс техписы не имеют доступа в исходники софта
Плюс техписы не имеют доступа в исходники софта
ну ты изобрел свою спеку как я понимаю, все так делают
тут минус что придется перепедалить все на чужой стандарт, плюсы - это открытый стандарт, это распространенный стандарт, то есть куча тулзов, библиотек и прочего, он поддерживается топами индустрии
я писал на хабре давно про плюсы-минусы https://habr.com/ru/company/rbkmoney/blog/488070/, но это чисто обзонрая статья, там парни с жуга неплохо недавно внутрянку расписали https://habr.com/ru/company/jugru/blog/525298/
тут минус что придется перепедалить все на чужой стандарт, плюсы - это открытый стандарт, это распространенный стандарт, то есть куча тулзов, библиотек и прочего, он поддерживается топами индустрии
я писал на хабре давно про плюсы-минусы https://habr.com/ru/company/rbkmoney/blog/488070/, но это чисто обзонрая статья, там парни с жуга неплохо недавно внутрянку расписали https://habr.com/ru/company/jugru/blog/525298/
AK
доступ к коду тебе при этом не нужен - у тебя есть спека, ты ее можешь описывать техписами параллельно с разработкой
я у себя это использую для ускорения разработки - сначала пишется спека, потом отдается в команды, например фронты могут замокать по спеке бэк и писать интерфейсы еще до того как бекендеры их разработают
я у себя это использую для ускорения разработки - сначала пишется спека, потом отдается в команды, например фронты могут замокать по спеке бэк и писать интерфейсы еще до того как бекендеры их разработают