Что использовать для ведения документации API?

Question

[tigra]

Сейчас используем для этого дела confluence, но это супер неудобно, когда нужно описать какой либо метод - я плачу. Рассматривал swagger, redoc, но эти инструменты по большей части предоставляют из себя визуальное представление файлика json/yaml который надо собрать в каком нибудь редакторе, а потом подгрузить.
Есть ли что то более простое?какой нибудь визуальный редактор где человек может авторизоваться, добавить раздел или новый метод и накидать быстро пример запроса/ответа?
Или как обычно выглядит правильный процесс ведения документации в том же swagger в других компаниях?

Answer 1

[Иван Шумов]

Сейчас Swagger является стандартом де-факто (Apigee, конечно, вообще вышка, но стоит как крыло от боинга). Скорее всего отсутствие опыта с ним вызывает такие сомнения. Есть SwaggerUI - его можно запустить у себя на сервере или же использовать как их сервис.

Идеальное проектирование - Top to bottom, когда сначала делается спецификация, а потом идет разработка, но иногда делают документацию в коде аннотациями, которая собирается в итоговую спецификацию (я против того чтобы генерировать, но так бывает нормально)

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

В общем - советую просто попробовать 1-2 API описать в нем чтобы набить руку и уже не отказываться