Search code examples
springspring-bootyamlswaggeropenapi

How to generate OpenAPI 3.0 YAML file from existing Spring REST API?

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?

Solution

  • 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.yaml. (to convert into yaml) 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>