How to run Swagger 3 on Spring Boot 3

Question

Using a fresh Spring Initialzr with Java17 and Spring Boot 3.0.0, and an extra addition to the pom.xml for Springfox Swagger 3, I can't for the life of me get Swagger pages to work. Instead, I get the whitelabel error page with 404.

Pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.0.0</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo</name>
<description>Demo project for Spring Boot</description>
<properties>
    <java.version>17</java.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>
</project>

The standard Swagger URLs as defined in this Github Issues page aren't working for the above pom.xml project.

Ahmed Tawfik · Accepted Answer · 2023-01-13T11:14:59.100

67

I had given up and went to use Spring Boot 2.7 after posting the question. But, after seeing Dmitriy's answer though, I checked Springdoc one last time and found that Springdoc v2 does support Spring Boot 3.

Essentially, one has to place the following in their pom:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.0</version>
   </dependency>

Then one can access the Swagger page using the following URL: http://localhost:8080/swagger-ui.html (Don't forget to add context path if you need it). For some reason, when opening, it redirects to http://localhost:8080/swagger-ui/index.html although going for that initially returned 404...

edited Jan 13 '23 at 11:14

answered Nov 30 '22 at 11:19

Ahmed Tawfik

1,159
1
8
13

Have you found any other solution to it except for downgrading the spring boot version @Ahmed – Tabish Hafeez Jan 04 '23 at 19:56
Hi @TabishHafeez. As the answer says, Spring Boot 3.0 is covered by SpringDoc 2.0 – Ahmed Tawfik Jan 05 '23 at 20:30

score 13 · Answer 2 · answered Dec 16 '22 at 18:29

13

in addition to adding springdoc-openapi-starter-webmvc-ui (v2.0.2 for me) as indicated in the accepted answer, I also needed to remove org.springdoc:springdoc-openapi-ui:1.6.13 .

It was there because I had tried it before. If present, there's still a non Jakarta reference that Spring tries to resolve (and fails to do so).

I also needed to add this dependency, otherwise I would have a nasty message at startup (version is resolved by Spring Boot BOM) :

implementation group: 'org.hibernate.validator', name: 'hibernate-validator'

answered Dec 16 '22 at 18:29

Vincent F

6,523
7
37
79

You needed hibernate for a bare bones Spring Boot 3 hello world app with swagger? – Ahmed Tawfik Mar 19 '23 at 00:46
not hibernate, but hibernate-validator, which is the standard implementation for Java Bean validation – Vincent F Mar 19 '23 at 07:05
1

@VincentF You may add a dependency on `spring-boot-starter-validation` which already provides (read abstracts) `hibernate-validator` – Mousa Halaseh Aug 01 '23 at 10:36

score 11 · Answer 3 · answered Dec 27 '22 at 02:42

11

Springdoc is working with Spring boot 3.0.1

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.2</version>
   </dependency>

Default URL: http://localhost:8080/swagger-ui/index.html

answered Dec 27 '22 at 02:42

Makara Set

333
3
4

1

Duplicate answer – Sathiamoorthy Apr 20 '23 at 11:08

score 7 · Answer 4 · answered Dec 23 '22 at 08:47

I agreed with @Ahmed Tawfik because I also faced the same. But today I tried that same approach with the new version of "springdoc-openapi-starter-webmvc-ui" dependency and Spring Boot 3.0.2-SNAPSHOT.

    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.2</version>
    </dependency>

because the previous one "springdoc-openapi-ui" is changed to the above one.

Also, include below the path to the security config for swagger UI.

"/v3/api-docs/**","/swagger-ui/**"

For my project,

@Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http.cors(AbstractHttpConfigurer::disable)
                .csrf(AbstractHttpConfigurer::disable)
                .exceptionHandling(exceptionHandlingConfigurer -> exceptionHandlingConfigurer.authenticationEntryPoint(unauthorizedHandler))
                .authorizeHttpRequests(authorizationManagerRequestMatcherRegistry -> {
                            try {
                                authorizationManagerRequestMatcherRegistry
                                        .requestMatchers(HttpMethod.POST, POST_AUTH_WHITELIST).permitAll()
                                        .requestMatchers(HttpMethod.GET, GET_AUTH_WHITELIST).permitAll()
                                        .requestMatchers("/v3/api-docs/**", "/swagger-ui/**").permitAll()
                                        .anyRequest()
                                        .authenticated()
                                        .and()
                                        .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS));
                            } catch (Exception e) {
                                throw new ResourceNotFoundException(e.getMessage());
                            }
                        }
                )
                .formLogin(AbstractHttpConfigurer::disable)
                .httpBasic(AbstractHttpConfigurer::disable).addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class)
                .authenticationProvider(daoAuthenticationProvider()).build();
    }

The swagger UI link will be:

http://server:port/context-path/swagger-ui.html

Please adjust the server, port, and context-path regarding your personal changes.

All the above steps are working fine with my project. I don't need extra configuration.

Also, you can add the custom path (Optional):

springdoc.swagger-ui.path=/swagger-ui.html

Here is the Official Documentation of OpenApi 3 and Spring Boot : https://springdoc.org/v2/#features

In the above documentation, you can explore additional configurations and other things also.

Happy Learning! ✌️

This need to be the accepted answer at 09/01/2023 – sineverba Jan 09 '23 at 14:49 — sineverba, Jan 09 '23 at 14:49

score 6 · Answer 5 · answered Nov 30 '22 at 05:44

6

Lastest springfox-boot-starter version 3.0.0 and springdoc-openapi-ui 1.6.13

seems not to support spring-boot 3.

We need to wait until the new version adopts jakarta.servlet package

answered Nov 30 '22 at 05:44

Dmitriy Baron

69
2

Here is already a GitHub issue opened for this case: https://github.com/springfox/springfox/issues/3983 (and several duplicate-issues) – Girts Strazdins Jan 30 '23 at 13:07
This is not true any more, use springdoc openapi 2.x.x – Honza Zidek Feb 28 '23 at 14:12
Aggre. org.springdoc springdoc-openapi-starter-webmvc-ui 2.0.2 – Dmitriy Baron Mar 01 '23 at 15:03

score 5 · Answer 6 · answered Dec 13 '22 at 11:51

5

For Gradle you can add this:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.0'

answered Dec 13 '22 at 11:51

Semih Biygit

101
3

score 3 · Answer 7 · answered Mar 18 '23 at 08:50

for Spring Boot 3, use springdoc-openapi v2

Here is the sample steps that is working on Spring Boot 3 and suports JWT based Authentication:

Add the following dependency in the pom.xml file:

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.0.4</version>
</dependency>

Create a new class called OpenApiConfig. In this example annotation-based configuration is used, but it can also be configured programmatically.

@Configuration
@OpenAPIDefinition(info = @Info(title = "REST API", version = "1.0",
        description = "REST API description...",
        contact = @Contact(name = "Name Surname")),
        security = {@SecurityRequirement(name = "bearerToken")}
)
@SecuritySchemes({
        @SecurityScheme(name = "bearerToken", type = SecuritySchemeType.HTTP, 
                        scheme = "bearer", bearerFormat = "JWT")
})

Then update your SecurityConfig class by adding necessary urls for access permission:

private static final String[] AUTH_WHITELIST = {
        "/api/v1/auth/**",
        "/v3/api-docs/**",
        "/v3/api-docs.yaml",
        "/swagger-ui/**",
        "/swagger-ui.html"
};

@Bean
public SecurityFilterChain filterChain(HttpSecurity httpSecurity) throws Exception{
    httpSecurity
            // ...
            .authorizeHttpRequests()
            .requestMatchers(AUTH_WHITELIST).permitAll()
            .anyRequest().authenticated();
    // ...
}

Run the app and access the documentation on http://localhost:8080/swagger-ui/index.html

score 2 · Answer 8 · answered Mar 06 '23 at 09:46

2

The latest version of springdoc-openapi is compatiable with Springboot 3 (jakarta) changes. Using the latest version solved the problem for me.

https://springdoc.org/v2/

answered Mar 06 '23 at 09:46

Manikandan Uthaman

21
3

score 1 · Answer 9 · answered Jan 16 '23 at 08:41

Following dependencies working fine to me.

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.sample.app</groupId>
    <artifactId>hello-world</artifactId>
    <version>1.0.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.0.1</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>


        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.0.0</version>
        </dependency>

    </dependencies>
</project>

score 1 · Answer 10 · answered Mar 14 '23 at 09:36

1

seems like the springfox version of swagger is not working for spring 3.0 . An alternative is openAPI. Add following dependency to make it work

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

answered Mar 14 '23 at 09:36

PKS

618
1
7
19

score 1 · Answer 11 · answered Apr 14 '23 at 06:21

For Spring boot 3 and Above we got here this dependency to add

   <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-common</artifactId>
        <version>2.1.0</version>
    </dependency>

and for a project which contains spring security, We need to permit the following path in order to ignore @AuthenticationPrincipal parameter.

    private static final String[] AUTH_WHITELIST = {
        "/api/v1/auth/**",
        "/v3/api-docs/**",
        "/v3/api-docs.yaml",
        "/swagger-ui/**",
        "/swagger-ui.html"
};

for more resource watch this or read this document

score 0 · Answer 12 · answered Dec 30 '22 at 08:15

0

Use Open API instead swagger for Spring v3.0. Follow this document Open API Docs

answered Dec 30 '22 at 08:15

Chameera W. Ashan

346
4
7

Your link is dead. – Roovy Jul 05 '23 at 18:45

score 0 · Answer 13 · answered Aug 28 '23 at 11:51

pom.xml
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.0.3</version>
</dependency>

application.properties

#springdoc.api-docs.enabled=false
#springdoc.swagger-ui.enabled=false

springdoc.swagger-ui.path=/bezkoder-documentation
springdoc.api-docs.path=/bezkoder-api-docs

springdoc.packages-to-scan=com.bezkoder.spring.swagger.controller
springdoc.swagger-ui.tryItOutEnabled=true
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha
springdoc.swagger-ui.filter=true
– Use api-docs.enabled=false if you want to disable springdoc-openapi endpoints.
– Use swagger-ui.enabled=false to disable the swagger-ui endpoint.

– api-docs.path is for custom path of the OpenAPI documentation in Json format. Now it is http://localhost:8080/bezkoder-api-docs.

– swagger-ui.path is for custom path of the Swagger documentation. If you visit http://localhost:8080/bezkoder-documentation, the browser will redirect you to http://localhost:8080/swagger-ui/index.html

– packages-to-scan=packageA,packageB: list of packages to scan with comma separated.
We also have packages-to-exclude, paths-to-match, paths-to-exclude.

– swagger-ui.tryItOutEnabled if you want to enable “Try it out” section by default

How to run Swagger 3 on Spring Boot 3

13 Answers13

Linked