如何从现有 Spring REST API 生成 OpenAPI 3.0 YAML 文件？

Question

我有一个现有的 Spring REST API，我想为其生成 OpenAPI 3.0 YAML 文件而不是 Swagger 2.0 JSON/YAML?

到目前为止，SpringFox 不支持 YAML 生成。它使用 Swagger 2.0（遵循 OPEN API 3.0 规范）生成 JSON。

还有https://github.com/openapi-tools/swagger-maven-plugin但是好像不支持Spring休息

我尝试了 Kongchen spring-maven-plugin，它能够生成 YAML 文件，但使用 Swagger 2.0 定义而不是 OPEN API 3.0，如：

swagger: "2.0"
info:
  description: "Test rest project"
  version: "1.0"
  title: "Some desc"
  termsOfService: "http://swagger.io/terms/"
  contact:
    name: "Rest Support"
    url: "http://www.swagger.io/support"
    email: "support@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "example.com"
basePath: "/api/"

所以我的问题是如何生成 OPEN API YAML 文件，例如：

openapi: 3.0.0
info:
  description: Some desc
  version: "1.0"
  title: Test rest project
  termsOfService: http://swagger.io/terms/
  contact:
    name: Rest Support
    url: http://www.swagger.io/support
    email: support@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

我目前正在使用 swagger-maven-plugin 生成带有 Swagger 2.0 定义的 YAML 文件，并使用 swagger2openapi 在 https://mermade.org.uk/openapi-converter[=20= 将其转换为 Open API 3.0 定义]

问题一：
spring-maven-plugin 可以捕获 io.swagger.v3.oas.annotations 生成 YAML 吗？

问题二：
在 Spring MVC 项目中使用 OPEN API 定义生成 YAML 的最佳方法是什么？

问题三：
io.swagger.v3.oas 可以与 Spring 项目一起使用还是只能用于 JAX-RS 项目？

Answer 1

我们最近使用了 springdoc-openapi java 库。它有助于使用 spring 引导项目自动生成 API 文档。

它会自动将 swagger-ui 部署到 spring-boot 应用程序文档将以 HTML 格式提供，使用官方 [swagger-ui jars]:

Swagger UI 页面将在 http://server:port/context-path/swagger-ui.html 上可用，OpenAPI 描述将在以下 url 上可用 json 格式: http://server:port/context-path/v3/api-docs

server: 服务器名称或IP
端口：服务器端口
context-path：应用程序的上下文路径

也可以在以下路径中以 yaml 格式获取文档：/v3/api-docs.yml。将库添加到项目依赖项列表中（无需额外配置）

 <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.2.3</version>
  </dependency>

Answer 2

我很长一段时间都没有为此错过一些图书馆。最后，决定实现我自己的生成器 https://github.com/jrcodeza/spring-openapi 也许你也可以看看。它基于反射并支持 javax 和 spring 注释。它还基于 Jackson 注释生成继承模型（带有鉴别器）。此外，如果您想更改生成过程（例如，当您有自己的注释并需要调整模式的生成部分时），您可以定义自己的拦截器。您可以在运行时模式下使用它或将其用作 Maven 插件。还有 OpenAPI3 to java 客户端生成器，它生成模型。它再次生成 Javax 注释和 Jackson 注释以实现正确的继承。

如何从现有 Spring REST API 生成 OpenAPI 3.0 YAML 文件？

How to generate OpenAPI 3.0 YAML file from existing Spring REST API?

spring

yaml

swagger

spring-boot

openapi