通过 Maven 使用 Swagger 2.x 生成 HTML 文档

Question

我正在考虑在我的几个不同项目中生成一些 API 文档，希望使用 Swagger。由于从未使用过 Swagger，我正在尝试找到一个非常简单的解决方案来通过 Maven 生成 HTML 文档。

这些项目中使用的底层 REST 框架是 Jersey。我找到了Swagger的文档，但似乎没有任何简单生成 HTML 文件的示例。他们的大多数示例似乎都将 API 文档嵌入到实际服务本身中。

所以我的问题是：

• 如何通过 Maven 使用 Swagger 生成 HTML 文档？
• 对于 REST 应用程序，将文档与服务一起附加是否正常？

Answer 1

您将需要使用 swagger-codegen 生成 HTML。

https://github.com/swagger-api/swagger-codegen#generate-static-html-api-documentation

要使用 swagger-codegen 生成 HTML 文档，您首先需要生成 OpenAPI 文档。由于您已经使用 Jersey 作为您的 REST 框架，因此将 swagger 作为依赖项引入您的项目并注释所有 API servlet 可能是最简单的方法。这样做会告诉 swagger 读取您的所有代码并生成 OpenAPI 规范。您可以按照https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration中的步骤开始。

祝你好运！