5

Есть несколько проектов, взаимодействующих друг с другом по http api или console api или еще как-нибудь.

Грубо говоря, проект состоит из приложений, приложения состоят из компонентов, компоненты состоят из интерфейсов и классов.

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

Подробно описывать методы классов нет необходимости, можно просто описать роль, цель, возможности. Или, может быть, только интерфейсы.

Какие есть инструменты для подобного документирования? Желательно с графиками отношений и более или менее удобным обновлением информации несколькими людьми, т.к. все постоянно дорабатывается.

На данный момент есть опыт работы с draw.io.

В принципе это все можно описать текстом + делать ссылки на draw.io, но может быть есть что-то еще.

UPD.

Примерно вижу это так:

  • Страница с диаграммой взаимодействия проектов (Что-то типа схемы базы данных)
  • Подобная страница с диаграммой взаимодействия компонентов внутри проекта
  • При переходе в проект видно описание и список компонентов и связанные проекты
  • При переходе в компонент видно описание, интерфейсы и связанные компоненты
3
  • 1
    Конечно Swagger не решит все ваши проблемы, но советую посмотреть в его сторону.
    – BruAPAHE
    7 мая 2019 в 9:42
  • Lucidchart - похож на draw.io, но значительно удобнее и имеют больше контента. Visual paradigm, Enterprise Architect. Visio. 8 мая 2019 в 6:24
  • http api я описываю через api blueprint и генерирую с помощью aglio. Для документирования кода подходит PHPDoc, если, конечно соответствующие комментарии в коде имеются.
    – ilyaplot
    7 авг 2019 в 9:20

1 ответ 1

2

Для документации api на php, есть, например: Swagger-php и API Platfor.

Если проекты на фреймворках, то для них есть расширения:

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

Но, это, скорей, последние два пункта...

Для генераций диаграмм, знаю ток PlantUML (например, если что-то такого надо)

но, чтоб объединить... если ток сохранить диаграмму как картинку и в пунктах "description" добавить: <img alt="example" src="../images/example.png" /> ![example](../images/example.png) (в доках надо посмотреть, у кого как)

Из сторонних, есть ещё: OpenAPI-generator, ReDoc, DapperDox

Ваш ответ

By clicking “Отправить ответ”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками или задайте свой вопрос.