如何使用 doxygen 创建公共网络服务器 api 文档？答案

【问题标题】：How to create a public webserver api documentation with doxygen?如何使用 doxygen 创建公共网络服务器 api 文档？
【发布时间】：2018-10-19 11:26:09
【问题描述】：

我想用php 构建一个webserver api，并想用doxygen 为api endpoints 生成一个公共文档。

到目前为止，我知道如何让 doxygen 用于我的内部代码文档，但我想创建第二个公共文档，它只描述公共网络服务器端点。

我想将相应的文档放入我的控制器和操作中，以便在开发时可以同时更新任何端点更改，而不必并行维护代码和文档。所以在一般情况下，我需要一种方法来以某种方式标记我的公共文档，并使 doxygen 白名单仅用于我的公共文档。

是否有实现此目标的标准或最佳实践方法？有哪些必要的配置步骤？是否有任何基于 doxygen 的工具可以提供帮助？

谢谢

【问题讨论】：

【解决方案1】：

一些起点：

您需要第二个 doxygen 配置文件 (Doxyfile)，其中包含两种情况的相关设置
您可能需要使用 \if、\ifnot \else、\endif、\cond 和 \endcond 以及 ENABLED_SECTIONS 等命令执行某些操作，请参阅文档。
根据函数的名称等，可能可以使用EXCLUDE_SYMBOLS
根据所有设置的方式，可能会减少外部文件集。

【讨论】：

感谢您的回复。是的，到目前为止我得到了第二个配置文件，但我不认为用 \if 和 \endif 包装我的所有文档块是一个可行的解决方案。有没有办法以相反的方式做到这一点，例如“除了带有部分/标签/注释 XYZ 的那些之外，不包括任何 cmets”？
排除所有 cmets 是不可能的，除了可能将每个文件包装在 \cond 块中并在您希望在外部文档中包含的位置终止它。

【解决方案2】：

我终于自己找到了解决方案。正确的方法是使用“OpenAPI”工具，这些工具通常与所有常见编程语言中的 swagger 语法兼容。（一些框架甚至提供内置支持，例如 LoopBack） OpenAPI 规范旨在为仅描述公共接口/API 端点的外部创建文档

【讨论】：