如何从现有 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 Rest。

我尝试了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: "[email protected]"
  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: [email protected]
  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

）将其转换为 Open API 3.0 定义

问题1：
spring-maven-plugin 可以捕获

io.swagger.v3.oas.annotations

来生成 YAML 吗？

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

问题3：

io.swagger.v3.oas

可以与 Spring 项目一起使用还是仅适用于 JAX-RS 项目？

Answer 1

我们最近使用了

springdoc-openapi

java 库。它有助于使用 Spring Boot 项目自动生成 API 文档。

它会自动将

swagger-ui

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

Swagger UI 页面应在

http://server:port/context-path/swagger-ui.html

可用，并且 OpenAPI 描述将在以下 json 格式的 url 中可用：

http://server:port/context-path/v3/api-docs

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

文档也可以以 yaml 格式提供，路径如下：

/v3/api-docs.yaml

。 （转换成yaml） 将库添加到项目依赖项列表中（无需额外配置）

 <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 到 java 客户端生成器，用于生成模型。同样，它还生成 Javax 注释和 Jackson 注释以实现正确的继承。