Spring Boot - Using SpringDoc OpenAPI

Previous
Quiz
Next

springdoc-openapi is an open source project used to generate API documentation for Spring Boot based projects. It examines application at runtime for API semantics based on spring configurations, class structures and annotations. It supports following APIs.

  • OpenAPI 3

  • Spring Boot 3

  • JSR-303 specification including @NotNull, @Min, @Max, and @Size.

  • Swagger-ui

  • OAuth 2

  • GraalVM native images

We're enabling Swagger UI in this example. To enable the Swagger in Spring Boot application, you need to add the following dependencies in our build configurations file.

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

For Gradle users, add the following dependencies in your build.gradle file.

compile group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.6.0'

That's it. No other configuration is required. We can check the API specifications in JSON using following URL −

http://server:port/<context-path>/v3/api-docs

and Swagger UI is accessible using following URL −

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

Let's add OpenAPI documentation support to our REST API example discussed in Spring Boot - Consuming RESTful Web Services Chapter.

The complete build configuration file is given below −

Maven 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.3.3</version>
      <relativePath/> <!-- lookup parent from repository -->
   </parent>
   <groupId>com.tutorialspoint</groupId>
   <artifactId>demo</artifactId>
   <version>0.0.1-SNAPSHOT</version>
   <packaging>jar</packaging>
   <name>demo</name>
   <description>Demo project for Spring Boot</description>
   <url/>
   <licenses>
      <license/>
   </licenses>
   <developers>
      <developer/>
   </developers>
   <scm>
      <connection/>
      <developerConnection/>
      <tag/>
      <url/>
      </scm>
      <properties>
         <java.version>21</java.version>
      </properties>
      <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.6.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </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>

Gradle build.gradle

buildscript {
   ext {
      springBootVersion = '3.3.3'
   }
   repositories {
      mavenCentral()
   }
   dependencies {
      classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
   }
}
apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'org.springframework.boot'

group = 'com.tutorialspoint'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = 1.8

repositories {
   mavenCentral()
} dependencies {
   compile('org.springframework.boot:spring-boot-starter-web')
   testCompile('org.springframework.boot:spring-boot-starter-test')
   compile group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.6.0'
}

Compilation and Execution

You can create an executable JAR file, and run the spring boot application by using the below Maven or Gradle commands as shown −

For Maven, use the command shown below −

mvn clean install

After "BUILD SUCCESS", you can find the JAR file under the target directory.

For Gradle, use the command shown below −

gradle clean build

After "BUILD SUCCESSFUL", you can find the JAR file under the build/libs directory.

You can run the JAR file by using the command shown below −

java jar <JARFILE>

This will start the application on the Tomcat port 8080 as shown below −


  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

[32m :: Spring Boot :: [39m              [2m (v3.3.3)[0;39m

[2024-09-17T17:37:50Z] [org.springframework.boot.StartupInfoLogger] [main] [50] [INFO ] Starting DemoApplication using Java 21.0.3 with PID 7760 (E:\Dev\demo\target\classes started by Tutorialspoint in E:\Dev\demo)
[2024-09-17T17:37:50Z] [org.springframework.boot.SpringApplication] [main] [654] [INFO ] No active profile set, falling back to 1 default profile: "default"
[2024-09-17T17:37:51Z] [org.springframework.boot.web.embedded.tomcat.TomcatWebServer] [main] [111] [INFO ] Tomcat initialized with port 8080 (http)
[2024-09-17T17:37:51Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Initializing ProtocolHandler ["http-nio-8080"]
[2024-09-17T17:37:51Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Starting service [Tomcat]
[2024-09-17T17:37:51Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Starting Servlet engine: [Apache Tomcat/10.1.28]
[2024-09-17T17:37:51Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Initializing Spring embedded WebApplicationContext
[2024-09-17T17:37:51Z] [org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext] [main] [296] [INFO ] Root WebApplicationContext: initialization completed in 1106 ms
[2024-09-17T17:37:51Z] [org.springframework.boot.autoconfigure.web.servlet.WelcomePageHandlerMapping] [main] [59] [INFO ] Adding welcome page template: index
[2024-09-17T17:37:52Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Starting ProtocolHandler ["http-nio-8080"]
[2024-09-17T17:37:52Z] [org.springframework.boot.web.embedded.tomcat.TomcatWebServer] [main] [243] [INFO ] Tomcat started on port 8080 (http) with context path '/'
[2024-09-17T17:37:52Z] [org.springframework.boot.web.embedded.tomcat.TomcatWebServer] [main] [111] [INFO ] Tomcat initialized with port 9000 (http)
[2024-09-17T17:37:52Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Initializing ProtocolHandler ["http-nio-9000"]
[2024-09-17T17:37:52Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Starting service [Tomcat]
[2024-09-17T17:37:52Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Starting Servlet engine: [Apache Tomcat/10.1.28]
[2024-09-17T17:37:52Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Initializing Spring embedded WebApplicationContext
[2024-09-17T17:37:52Z] [org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext] [main] [296] [INFO ] Root WebApplicationContext: initialization completed in 80 ms
[2024-09-17T17:37:52Z] [org.springframework.boot.actuate.endpoint.web.EndpointLinksResolver] [main] [60] [INFO ] Exposing 1 endpoint beneath base path '/actuator'
[2024-09-17T17:37:52Z] [org.apache.juli.logging.DirectJDKLog] [main] [173] [INFO ] Starting ProtocolHandler ["http-nio-9000"]
[2024-09-17T17:37:52Z] [org.springframework.boot.web.embedded.tomcat.TomcatWebServer] [main] [243] [INFO ] Tomcat started on port 9000 (http) with context path '/'
[2024-09-17T17:37:52Z] [org.springframework.boot.StartupInfoLogger] [main] [56] [INFO ] Started DemoApplication in 2.378 seconds (process running for 3.241)
[2024-09-17T17:37:53Z] [org.apache.juli.logging.DirectJDKLog] [RMI TCP Connection(4)-127.0.0.1] [173] [INFO ] Initializing Spring DispatcherServlet 'dispatcherServlet'
[2024-09-17T17:37:53Z] [org.springframework.web.servlet.FrameworkServlet] [RMI TCP Connection(4)-127.0.0.1] [532] [INFO ] Initializing Servlet 'dispatcherServlet'
[2024-09-17T17:37:53Z] [org.springframework.web.servlet.FrameworkServlet] [RMI TCP Connection(4)-127.0.0.1] [554] [INFO ] Completed initialization in 1 ms
Remote Host:0:0:0:0:0:0:0:1
Remote Address:0:0:0:0:0:0:0:1
Pre Handle method is Calling
[2024-09-17T17:38:43Z] [org.springdoc.api.AbstractOpenApiResource] [http-nio-8080-exec-1] [390] [INFO ] Init duration for springdoc-openapi is: 148 ms

Output

Now hit the URL shown below in browser to see APIs in JSON Format.

http://localhost:8080/v3/api-docs

API Specifications

Now hit the URL shown below in browser to see API documentation in Swagger UI.

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

Swagger UI
Print Page
Previous
Next
Advertisements