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

问题

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.

回答1:

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
})

回答2:

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 dependecnies 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

回答3:

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;
}

回答4:

You can do it with @Annotations too:

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

来源：https://stackoverflow.com/questions/59871209/how-to-integrate-open-api-3-with-spring-project-not-spring-boot-using-springdo

标签

java

Spring

swagger-ui

openapi

springdoc