Как лучше документировать API в ruby on rails?

Question

[Николай Марков]

Чем вы пользуетесь для написания документации к API? Хотелось бы услышать про личный опыт использования различных инструментов.

В данный момент склоняюсь к использованию yard.

Answer 1

[Viktor Vsk]

Википедия - тоже вариант, когда участвовать должны менеджеры, тестрировщики и заказчики, или команды заказчика\аутсорса

Comments

[Николай Марков]

И блокнот тоже вариант и markdown. Это все понятно. Хотелось бы про опыт использования каких-то инструментов услышать

[Viktor Vsk]

Николай Марков: все ,что вы перечислили - это инструменты. Блокнот + гит на крайняк нормально подойдет, если работаете один. А вот википедия будет оверхедом.

Mashape и swagger - хорошее решение, когда делаете качественное публичное апи, которым будут пользоваться, потенциально, тысячи сторонних разработчиков.

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

[Николай Марков]

Ладно. разве кто-то делает апи не публичное? Риторический вопрос. Да мне нужно сделать качественную документацию для сторонних разработчиков. Mashape не подходят из-за vendor-lock'а. У swagger'а какая-то печальная поддержка в ruby.

[Viktor Vsk]

Николай Марков: Может, я не так выразился, конечно, но, мне кажется, что под публичным - имеется ввиду для всех подряд. Под приватным - по приватному апи ключу. Например, когда вы делаете бэкэнд и мобильное приложение.

Разница в чем. В том, что в этом случае, все вопросы, которые появляются у пользователей АПИ - вы 100% обязаны решать в кратчайшие сроки.