28

I have a project (Spring Boot App + Kotlin) that I would like to have an Open API 3.0 spec for (preferably in YAML). The Springfox libraries are nice but they generate Swagger 2.0 JSON. What is the best way to generate an Open Api 3.0 spec from the annotations in my controllers? Is writing it from scratch the only way?

ladyskynet
  • 297
  • 1
  • 3
  • 10
  • Springfox feature request to support OpenAPI 3.0: https://github.com/springfox/springfox/issues/2022 – Helen May 29 '19 at 14:09

5 Answers5

26

We have used springdoc-openapi library in our kotlin project, and it meets our need for automating the generation of API documentation using spring boot projects.

It automatically deploys swagger-ui to a spring-boot application

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

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.32</version>
  </dependency>
  • I added this dependency in pom. The jar is downloaded. It is added in maven dependencies, but I am not able to see OpenApi description at the path you mentioned. For me the path is: http://localhost:15730/context-path/v3/api-docs Could you please assist? – pan1490 Apr 02 '20 at 12:56
  • "context-path" is the context of your spring application, usually it's "/" if not modified :) – funder7 Mar 19 '21 at 23:59
5

You could look at spring-restdocs and restdocs-api-spec.

spring-restdocs takes a test-driven approach to API documentation which has many advantages over the introspection-driven approach spring-fox uses. restdocs-api-spec is an extension for spring-restdocs that adds API specification support. Currently it supports OpenAPI2 OpenAPI3 and Postman.

Mathias Dpunkt
  • 11,594
  • 4
  • 45
  • 70
3

I 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 (e.g. 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 from openapi3 spec. Again it generates also Javax annotations and Jackson annotations for correct inheritance.

Jakub Remenec
  • 71
  • 1
1

You can also refer to https://www.baeldung.com/spring-rest-openapi-documentation which provides a tutorial on implementing OpenAPI 3.0 with a SpringBoot 1.x or 2.x application using springdoc-openapi.

To summarize, you just add the maven dependency for springdoc-openapi into your application and when you bootRun, go to path http://server:port/v3/api-docs.yaml/ and you will download an Open API 3.0 spec file in yaml, generated from your application's code.

You can do some other stuff with springdoc-openapi, by accessing the following when your SpringBoot application is running:

Jonathan Lee
  • 1,302
  • 1
  • 7
  • 15
0

If you're using jax-rs this tutorial helps. It uses the Apache CXF implementation. I couldn't find any other implementation of jaxrs that uses Spring Boot AND generate Open API 3.0 spec.

You'll need these depedencies:

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId>
    <version>3.2.4</version>
</dependency>

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>3.13.6</version>
</dependency>

Here is the general configuration, more detail is in the link:

@Configuration
@EnableAutoConfiguration
@ComponentScan(basePackageClasses = PeopleRestService.class)
public class AppConfig {
    @Autowired private PeopleRestService peopleRestService;
    @Bean(destroyMethod = "destroy")
    public Server jaxRsServer(Bus bus) {
        final JAXRSServerFactoryBean factory = new JAXRSServerFactoryBean();
        factory.setApplication(new JaxRsApiApplication());
        factory.setServiceBean(peopleRestService);
        factory.setProvider(new JacksonJsonProvider());
        factory.setFeatures(Arrays.asList(new OpenApiFeature()));
        factory.setBus(bus);
        factory.setAddress("/");
        return factory.create();
    }
    @Bean
    public ServletRegistrationBean cxfServlet() {
        final ServletRegistrationBean servletRegistrationBean = new ServletRegistrationBean(new CXFServlet(), "/api/*");
        servletRegistrationBean.setLoadOnStartup(1);
        return servletRegistrationBean;
    }
}

https://dzone.com/articles/moving-with-the-times-towards-openapi-v300-adoptio

Jerry Li
  • 49
  • 1
  • 5