API портал: на что обратить внимание при дизайне. Опыт Wrike

[shuron]

Вопрос в студию..

Есть спеки API в формате Open API 3. Допустим они хорошо проработаные и документированы…
Надо автоматически генерировать документацию + удобно дописывать и линковать дополнительные (преимущественно текстовые) страницы не описаные в самом Open API документе, но выдержаные в том же стиле естественно в конечном результате?

Есть тулы которые из Open API генерят документацию более менее красиво, но не увидел там возможности интграции доп. содержания.
Может у кго-то есть ссылки на готовый Пайплайн даже? перед тем как начну костылять что-то? ;)

[aviskase]

У Redoc есть PRO версия с порталом. Обычная версия может подгружать внешний маркдаун для info.description. Возможно, можно накостылить на основе этого.

[pavtaras]

А что используете для ведения документации? Swagger? UI для этого дела 100% свой или вы апгрейдили какой-то опенсорсный продукт?

[chak_zefir]

Рассматривали Swagger изначально, но на текущий момент у нас документация генерируется и парсится из JavaDoc самописными инструментами, не было смысла тратиться на изменение этого, поэтому оставили как есть, практически без изменений. Все эти данные передаём через GraphQL, а на клиенте используем Angular Universal.

[crimco]

Уважаемые специалисты! Подскажите пожалуйста- какие технологии использованы на этом сайте?
Смотрю код страницы- и не вижу ничего(
view-source:https://developers.wrike.com/

[AngelinaCooly]

Документация генерируется и парсится из JavaDoc самописными инструментами. Данные передаём через GraphQL, а на клиенте используем Angular Universal.