Что лучше apiDoc или swagger?

Question

[Александр Зубарев]

Есть проект на php, и апи этого проекта недокументированно никак.
Поискал и сходу нашёл два решения:
- Swagger
- apiDoc

Как понимаю суть у них одинаковая, на основе аннотаций строится документация.
Попытался определить плюсы и минусы.
- Swagger мне показался более гибким, можно прямо на лету сгенерировать доку, но аннотации слишком объемные и захламляют код.
- apiDoc менее гибкая, но более человеко-понятные аннотации.

Кто пользовался распишите плюсы и минусы, или может еще какое решение есть?

Comments

[hOtRush]

Swagger намного популярный и более гибкий/функциональный.

[Александр Зубарев]

hOtRush, да мне так тоже показалось. Но вот думаю нужна ли мне такая гибкость и не будет такого, что другой разработчик посмотрит на аннотации, испугается, и ничего не будет делать. Хотелось наверно больше простоты, гибкостью можно пожертвовать

[Construct]

Александр Зубарев, можно не через аннотации в коде и автогенерацию, а самому писать определение OpenAPI (например, desing-first approach, когда до каких-либо реализаций пишется спецификация, а потом по ней реализуют).
Для упрощения написания есть разные графические инструменты, например, Reprezen Studio (не пробовал), Stoplight (пробовал, прикольный, пока поддерживает только OAS 2.0, но в разработке поддержка 3.0 и новые фичи).

[yanis_kondakov]

У себя на проекте используем Swagger. Недавно переписывал со старой версии на версию 3. Не столкнулся ни с одной проблемой. Зато добавилось очень много полезных штук.

Answer 1

[Dimonchik]

у swagger пользователей больше апидока в 20+ раз, смотрите на апидок как на ваше кастомное решение, а на сваггер - как на пром стандарт

Answer 2

[mamont80]

Кстати swagger уже устарел. Смотри лучше open api 3. И ещё, есть куча утилит, с помощью которых можно относительно легко самому генерить доки. Я пошел этим путём по swagger, так как стандартные генераторы не понравились