Дамы и господа камунданты, есть следующий вопрос.
У заказчика много разных систем, которые интегрируются через Камунду. Нужно задокументировать все эти API. Мне нужно найти систему которая будет генерировать документацию на API.
Пока я нашел следующие альтернативы Swagger:
1. I/O Docs (
https://github.com/mashery/iodocs )
2. Redoc, кажется надстройка над Свагером (
https://github.com/Redocly/redoc )
3. Радикальный метод: Не использовать никакую систему документации, а вместо этого заставлять разработчиков у каждой конечной точки (endpoint) поддерживать метод OPTIONS. В ответе на запрос OPTIONS присылать в ответе документацию (текстом).
4. RAML (
https://raml.org/ )
5. API Blueprint (
https://apiblueprint.org/ )
Кажется, что выбирать надо между Свагером, RAML и API Blueprint.
Если у кого-нибудь из присутствующих есть опыт работы с этими системами, буду признателен за сообщение. Особенно интересуют подводные камни и неочевидные трудности.