如何从现有的 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: "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
• 端口：服务器端口
• 上下文路径：应用程序的上下文路径

文档也可以 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 到 java 客户端生成器，它生成模型。 同样，它还会生成 Javax 注释和 Jackson 注释以进行正确的继承。