Как создать общедоступную документацию api веб-сервера с помощью doxygen?
Я хотел бы собрать webserver api с php и хочу создать общедоступную документацию для api endpoints, используя doxygen.
Пока я знаю, как заставить doxygen работать с моей внутренней документацией по коду, но я хотел бы создать вторую общедоступную документацию, которая описывает только конечные точки общедоступного веб-сервера.
Я хотел бы поместить соответствующую документацию в свои контроллеры и действия, чтобы любые изменения конечных точек можно было обновлять одновременно при разработке, вместо того, чтобы поддерживать код и документацию параллельно. Так что в gerenal мне нужен способ как-то пометить мои общедоступные документы и сделать их белый список doxygen только для моей общедоступной документации.
Есть ли стандартный или передовой способ добиться этого? Какие шаги необходимы для настройки? Есть ли какие-нибудь инструменты на основе doxygen, которые могут помочь?
Спасибо
Ответы 2
Некоторые отправные точки:
- Вам понадобится второй файл конфигурации doxygen (Doxyfile) с соответствующими настройками для обоих случаев.
- вам, вероятно, нужно что-то сделать с такими командами, как
\if,\ifnot\else,\endif,\condи\endcond, а такжеENABLED_SECTIONS, см. документацию. - в зависимости от названий функций и т. д. возможно использование
EXCLUDE_SYMBOLS - в зависимости от того, как все настроено, можно уменьшить внешний набор файлов.
Исключение всех комментариев невозможно, кроме, возможно, оборачивания каждого файла в блоке \cond и завершения этого в тех местах, которые вы хотите иметь во внешней документации.
Наконец-то я сам нашел решение. Правильный способ сделать это - использовать инструменты «OpenAPI», которые часто совместимы с синтаксисом swagger во всех распространенных языках программирования. (некоторые фреймворки даже предоставляют встроенную поддержку, например, LoopBack) OpenAPI-спецификации предназначены для создания документации для внешних устройств, описывающей только общедоступные интерфейсы / конечные точки API.
Спасибо за ваш ответ. да, пока у меня есть второй файл конфигурации, но я не думаю, что упаковка всех моих блоков документов с помощью \ if и \ endif является выполнимым решением. есть ли способ сделать это наоборот, например, «не включать никаких комментариев, кроме тех, которые имеют раздел / тег / аннотацию XYZ»?