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

Question

我想要为其生成 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 项目？

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
• port:服务器端口
• context-path:应用的上下文路径

文档也可以以 yaml 格式提供，位于以下路径:/v3/api-docs.yml。将库添加到项目依赖项列表中(无需额外配置)

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