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

Question

我想使用 PHP 构建一个 Web 服务器 API，并希望使用 doxygen 为 API 端点生成公共文档。

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

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

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

Answer 1

一些出发点：

• 您需要第二个 doxygen 配置文件（Doxyfile），其中包含两种情况的相关设置
• 您可能需要使用

  \if

  、

  \ifnot

  \else

  、

  \endif

  、

  \cond

  和

  \endcond

  以及

  ENABLED_SECTIONS

  等命令执行某些操作，请参阅文档。
• 根据函数名称等，可能可以使用

  EXCLUDE_SYMBOLS

• 根据一切设置的方式，可能会减少外部文件集。

Answer 2

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