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

【问题标题】：How to generate OpenAPI 3.0 YAML file from existing Spring REST API?如何从现有的 Spring REST API 生成 OpenAPI 3.0 YAML 文件？
【发布时间】：2019-07-22 02:21:09
【问题描述】：

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

从现在开始，SpringFox 不支持 YAML 生成。它使用 Swagger 2.0（遵循 OPEN API 3.0 规范）生成 JSON。

另外还有https://github.com/openapi-tools/swagger-maven-plugin，但是好像不支持Spring Rest。

我尝试了能够生成 YAML 文件但具有 Swagger 2.0 定义而不是 OPEN API 3.0 之类的 Kongchen spring-maven-plugin：

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 文件，并在 https://mermade.org.uk/openapi-converter 使用 swagger2openapi 将其转换为 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 项目？

【问题讨论】：

也许这会有所帮助 - stackoverflow.com/questions/49616529/…
即从现有的 OPEN API YAML 文件生成代码存根。我的问题是如何反之亦然。
你能解决这个问题吗？我也在寻找一种方法来为我的 Spring Boot 项目生成 YAML 文件。
@Alig 问题本身有解决方法来实现这一点。虽然还没有直接的方法。我们将不得不等到 SpringFox 3.0 发布。
使用 github.com/Mermade/oas-kit/tree/master/packages/swagger2openapi 将 Swagger 2 Doc 转换为 OpenAPI 3.0 规范。

标签： spring spring-boot yaml swagger openapi

【解决方案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.yml。将库添加到项目依赖项列表中（无需额外配置）

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

【讨论】：

确实很棒！等待 SpringFox 3.0 已经很久了：p
您好，所有文档都与将它与 spring boot 一起使用有关，那么没有 spring boot 的 spring rest 应用程序呢？
路径为/v3/api-docs.yaml。你上面有一个拼写错误。
太棒了！可以免去添加SpringFox.Swagger注解
@NunoSilva Springdoc 在没有 Spring Boot 的情况下与 SpringMVC 完美配合。

【解决方案2】：

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

【讨论】：