OpenAPI simplifies API documentation and testing by providing an interactive interface and machine-readable documentation. This guide will show you how to integrate OpenAPI into your Spring Boot application using SpringDoc.
OpenAPI simplifies API documentation and testing by providing an interactive interface and machine-readable documentation. This guide will show you how to integrate OpenAPI into your Spring Boot application using SpringDoc.
In this section, we clarify Why Use OpenAPI? and summarize the key points you will apply in implementation.
📋 Ensure you have the following:
To integrate OpenAPI using SpringDoc, add the following dependency to your Spring Boot project:
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.1.0</version> </dependency>
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
SpringDoc requires minimal configuration. You can customize your OpenAPI documentation using the application.properties or application.yml file.
Use this configuration as a baseline and adjust values for your local or production environment.
springdoc.api-docs.path=/api-docs springdoc.swagger-ui.path=/swagger-ui.html
Add annotations to your REST controllers and models to generate OpenAPI documentation automatically.
Run the application using the following command:
./mvnw spring-boot:run
Access the OpenAPI documentation at:
http://localhost:8080/api-docshttp://localhost:8080/swagger-ui.htmlYou can test the generated API documentation by exploring the Swagger UI interface:
http://localhost:8080/swagger-ui.html in your browser.You now have a practical Spring Boot with OpenAPI implementation with a clear, production-friendly Spring Boot structure. As a next step, adapt configuration and tests to your own domain, then validate behavior under realistic traffic and failure scenarios.
Controller Example
package com.example.openapi.controller; import com.example.openapi.model.User; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.responses.ApiResponse; import org.springframework.web.bind.annotation.*; import java.util.List; @RestController @RequestMapping("/users") public class UserController { @Operation(summary = "Get all users", description = "Retrieve a list of users") @ApiResponse(responseCode = "200", description = "Successful operation", content = @Content(mediaType = "application/json")) @GetMapping public List<User> getAllUsers() { return List.of(new User(1L, "John Doe", "john@example.com")); } @Operation(summary = "Create a new user", description = "Add a new user to the system") @ApiResponse(responseCode = "201", description = "User created successfully", content = @Content(mediaType = "application/json")) @PostMapping public User createUser(@RequestBody User user) { return user; } }
User Model
package com.example.openapi.model; import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; @Data @NoArgsConstructor @AllArgsConstructor public class User { private Long id; private String name; private String email; }
Controller Example
package com.example.openapi.controller import com.example.openapi.model.User import io.swagger.v3.oas.annotations.* import io.swagger.v3.oas.annotations.responses.* import io.swagger.v3.oas.annotations.media.* import org.springframework.web.bind.annotation.* @RestController @RequestMapping("/users") class UserController { @Operation(summary = "Get all users", description = "Retrieve a list of users") @ApiResponse(responseCode = "200", description = "Successful operation", content = [Content(mediaType = "application/json")]) @GetMapping fun getAllUsers(): List<User> = listOf(User(1L, "John Doe", "john@example.com")) @Operation(summary = "Create a new user", description = "Add a new user to the system") @ApiResponse(responseCode = "201", description = "User created successfully", content = [Content(mediaType = "application/json")]) @PostMapping fun createUser(@RequestBody user: User): User = user }
User Model
package com.example.openapi.model data class User( val id: Long, val name: String, val email: String )