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页面，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>

Answer 2

我为此长时间缺少一些图书馆。最后，决定实现自己的生成器https://github.com/jrcodeza/spring-openapi，也许您也可以检查一下。它基于反射并支持javax和spring注释。它还根据Jackson注释生成继承模型（带有区分符）。此外，如果您想更改生成过程（例如，当您拥有自己的注释并且需要调整生成的模式部分时），则可以定义自己的拦截器。您可以在运行时模式下使用它，也可以将其用作Maven插件。还有用于Java客户端生成器的OpenAPI3，用于生成模型。再次生成Javax注释和Jackson注释以正确继承。

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

2 个答案: