Как правильно писать документацию REST API?

Question

[Роман]

Вопрос как правильно писать документацию для мобильного приложения.

Я первый раз делаю REST API на YII2.

Начал писать документацию в Google Doc но это очень не удобно.

Какие есть решения что бы можно было для разработчиков IOS or ANDROID написать документацию.
Спасибо.

Answer 1

[Yuri Shikanov]

Где писать документацию, в Google Docs, Markdown прям в репозитории или что-то еще - не важно, главное чтобы вам было удобно.
Важно чтобы эта документация была максимально полной и точной.
Как вариант можете посмотреть raml, если хочется специализированный формат.

Answer 2

[Олег Гамега]

мне очень нравится https://apiary.io/

Answer 3

[Назар Мокринский]

Markdown обычно удобный вариант - простой синтаксис для написания вручную, можно прямо из IDE редактировать, удобно на том же GitHub читать, не потеряется если ложить вместе с исходным кодом.

Answer 4

[Nikolai]

я бы посмотрел в сторону RAML, как посоветовал Yuri Shikanov, а так же на сервис anypoint от mulesoft, который использует RAML и предоставляет консоль и дизайнер.