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

Question

I have an existing Spring REST API for which I want to generate the OpenAPI 3.0 YAML file and not Swagger 2.0 JSON/YAML?

Since as of now, SpringFox does not support YAML generation. It generates JSON with Swagger 2.0 (which follows OPEN API 3.0 spec).

Also, there is https://github.com/openapi-tools/swagger-maven-plugin but it does not seem to support Spring Rest.

I tried the Kongchen spring-maven-plugin which is able to generate the YAML file but with Swagger 2.0 definition and not OPEN API 3.0 like :

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/"

So my question is how can I generate the OPEN API YAML file like :

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

I am currently using swagger-maven-plugin to generate YAML file with Swagger 2.0 definition and converting it to Open API 3.0 definition using swagger2openapi at https://mermade.org.uk/openapi-converter

Question 1:
Can spring-maven-plugin capture io.swagger.v3.oas.annotations to generate the YAML ?

Question 2:
What is the best way to generate the YAML with OPEN API definitions in a Spring MVC Project?

Question 3:
Can io.swagger.v3.oas be used with Spring projects or it is only for JAX-RS projects?

Answer 1

We have used lately springdoc-openapi java library. It helps automating the generation of API documentation using spring boot projects.

It automatically deploys swagger-ui to a spring-boot application Documentation will be available in HTML format, using the official [swagger-ui jars]:

The Swagger UI page should then be available at http://server:port/context-path/swagger-ui.html and the OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs

• server: The server name or IP
• port: The server port
• context-path: The context path of the application

Documentation can be available in yaml format as well, on the following path: /v3/api-docs.yml . Add the library to the list of your project dependencies (No additional configuration is needed)

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

Answer 2

I was missing some library for this for longer time. Finally, decided to implement my own generator https://github.com/jrcodeza/spring-openapi maybe you can check it out too. It's based on reflection and supports javax and spring annotations. It also generates inheritance model (with discriminators) based on Jackson annotations. Besides you can define your own interceptors if you want to alter generation process (eg when you have your own annotations and need to adjust generated sections of schema). You can use it in runtime mode or as a maven plugin. There is also OpenAPI3 to java client generator, which generates the model. Again it generates also Javax annotations and Jackson annotations for correct inheritance.