How to Integrate Open API 3 with Spring project (not Spring Boot) using springdoc-openapi

Question

My Existing Project is on Spring Framework not Spring Boot.

I want to integrate Open API 3 with it.

I want to integrate using springdoc-openapi not using Jersey.

Answer 1

The ui load for spring-mvc (5.3.1) using springdoc-openapi-ui 1.5.2 looks more simple:

build.gradle (gradle version 6.5)

implementation 'org.springdoc:springdoc-openapi-ui:1.5.2'

The spring-boot-autoconfigure and spring-boot are not needed explicitly in dependencies section cause org.springdoc:springdoc-openapi-ui:1.5.2 already has them both (version 2.4.0). You'll be surprised how many and what dependencies will be added to your final application.

OpenApiConfig.java

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = {"org.springdoc"})
@Import({org.springdoc.core.SpringDocConfiguration.class,
         org.springdoc.webmvc.core.SpringDocWebMvcConfiguration.class,
         org.springdoc.webmvc.ui.SwaggerConfig.class,
         org.springdoc.core.SwaggerUiConfigProperties.class,
         org.springdoc.core.SwaggerUiOAuthProperties.class,
         org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class})

class OpenApiConfig implements WebMvcConfigurer {
}

The OpenApiConfig package should be covered by component scan.

In case of Spring Security usage, you might add two url patterns and define the role in your code for the OpenAPI pages access.

<security:intercept-url pattern="/swagger*/**" access="ROLE_DEVELOPER"/>
<security:intercept-url pattern="/v3/api-docs" access="ROLE_DEVELOPER"/>

The urls to check:

http://localhost:8080/your_context_path/swagger-ui.html
http://localhost:8080/your_context_path/v3/api-docs

Answer 2

You can do it with @Annotations:

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.servers.Server;
import io.swagger.v3.oas.annotations.info.Info

@OpenAPIDefinition(info = @Info(title = "My REST API", version = "1.2.6",
            description = "My OpenAPIDefinition description"),
                servers = { @Server(url = "/my-api", description = "Default URL")})
public class OpenApiConfig { }

Dependency of Springdoc OpenAPI UI on Maven Central Repository:

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

Maven Central Repository:

• https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

Answer 3

Even your application is using spring without (spring-boot), it should work. You need to add beans and dependencies auto-configuration that are natively provided in spring-boot.

You mainly, need to add the springdoc-openapi module and scan for the springdoc auto-configuration classes that spring-boot automatically loads for you. Depending on your module, you can find them on the file: spring.factories of each springdoc-openapi module.

For example, lets assume you want load the swagger-ui in spring-mvc application, and you are using spring.version=5.1.12.RELEASE, and you

You can add the following dependency:

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

If you don't have the spring-boot and spring-boot-autoconfigure dependencies, you need to add them. And pay attention to the compatibility matrix, between you spring.verion and spring-boot.version. For example, in this case (spring.version=5.1.12.RELEASE):

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot</artifactId>
    <version>2.1.11.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure</artifactId>
    <version>2.1.11.RELEASE</version>
</dependency>

In this case, as we want to load the ui for spring-mvc, you will need to add the following in one of your configuration classes:

@Import({ org.springdoc.core.SpringDocConfiguration.class, 
          org.springdoc.core.SpringDocWebMvcConfiguration.class,
          org.springdoc.ui.SwaggerConfig.class, 
          org.springdoc.core.SwaggerUiConfigProperties.class,
          org.springdoc.core.SwaggerUiOAuthProperties.class,
          org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class
})

Answer 4

Here is a sample project built with Spring and an embedded Undertow web server: https://github.com/essentialprogramming/undertow-spring-web No Spring Boot, even if it behaves like one. Just run the Server.main class. There you go, Open API will be available under http://localhost:8080/apidoc

You just need to decorate the Spring WebApplicationContext with the required beans:

private static  AnnotationConfigWebApplicationContext createSpringWebAppContext(String configLocation) {
    AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
    context.setConfigLocation(configLocation);
    context.register(
            org.springdoc.core.SwaggerUiConfigProperties.class, org.springdoc.core.SwaggerUiOAuthProperties.class,
            org.springdoc.core.SpringDocConfiguration.class, org.springdoc.core.SpringDocConfigProperties.class,
            org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class);
    return context;
}

Answer 5

In my Case to load the swagger-ui.html page, I used spring version 5.3.3 and springdoc-openapi-ui version 1.5.2.

My class configuration is:

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.example")
@Import({org.springdoc.core.SpringDocConfiguration.class,
         org.springdoc.webmvc.core.SpringDocWebMvcConfiguration.class,
         org.springdoc.webmvc.ui.SwaggerConfig.class,
         org.springdoc.core.SwaggerUiConfigProperties.class,
         org.springdoc.core.SwaggerUiOAuthProperties.class,
         org.springdoc.core.SpringDocConfigProperties.class,
         org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class})
public class WebConfig implements WebMvcConfigurer{

}

and my pom:

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

Answer 6

Documenting a Spring REST API Using OpenAPI 3.0

To document your spring boot application with OpenAPI 3.0, use this excellent article by baeldung.

https://www.baeldung.com/spring-rest-openapi-documentation

Further, you can change the URI path of the swagger too.

springdoc.swagger-ui.path=/swagger

The above /swagger specifies my context path to host swagger.

now, my URI path to access my swagger dashboard becomes :

http://localhost:8080/swagger