在 Spring Boot 中自动生成 API 文档 [关闭]

Posted 2023-04-15

【中文标题】在 Spring Boot 中自动生成 API 文档 [关闭]

【英文标题】：Automate generation of API documentation in Spring Boot [closed]

【发布时间】：2022-01-16 07:48:01

【问题描述】：

我想在 spring-boot 项目中自动生成 API 文档，我看到了两个选项：

springdoc-openapi：通过在运行时检查应用程序以根据 spring 配置、类结构和各种注释推断 API 语义

OpenAPI 生成器：根据 OpenAPI 规范生成代码 - 至少是 REST 控制器将实现的模型和接口

我不喜欢 springdoc-openapi 的地方是它用一堆注释来描述 API 污染了代码。

另一方面，我对 OpenAPI Generator 生成模型不太满意，因为可能会出现特殊要求，我必须以无法控制的方式自定义模型它。

我知道没有最好的方法，但我想知道其他人认为最适合他们的方法。

【参考方案1】：

这是基于边缘意见的，但这是我对此的看法。我总是使用springdoc 并依赖基于注释生成的文档。主要原因是如果文档与代码本身并排，则更容易维护文档。如果您更改代码，那么不要忘记更改文档会更容易。如果您担心污染代码，您可以使用一个界面来添加所有需要的注释，但这样会增加忘记更新文档的可能性。

我不太喜欢的另一种方法是因为我更喜欢让代码“生成”文档，而不是相反。对我来说，代码为王，因此它应该引领潮流。