如何从现有的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应用程序中。使用官方的[swagger-ui jars]，将以HTML格式提供文档：

然后，应该在http：// server：port / context-path / swagger-ui.html上提供Swagger UI页面，并且在以下URL中可以使用json格式的OpenAPI描述：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>