In modern API development, OpenAPI documentation and Swagger UI are very powerful tools. It is very useful for documenting and testing the APIs. In this article, we will learn to integrate OpenAPI docs and Swagger UI into our Spring Boot 3 project.

OpenAPI

According to the official documentation,
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs.
An OpenAPI file allows you to describe your entire API, including:

• Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)
• Operation parameters Input and output for each operation
• Authentication methods
• Contact information, license, terms of use, and other information.

This documentation is written in YAML or JSON.

Swagger

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume REST APIs.

springdoc-openapi

springdoc-openapi java library used to automate the generation of API documentation in spring boot projects. This library automatically generates API documentation in JSON/YAML and HTML format APIs.

Let's get started

We will explore how to integrate the OpenAPI documentation and Swagger UI into a Spring Boot 3 project using the springdoc-openapi.

Requirements

Before diving into the integration, ensure you have the following:

• Java Development Kit (JDK) 17 or later
• Spring Boot 3.x
• Maven or Gradle
• IDE (e.g., IntelliJ IDEA, Eclipse)

Add Dependencies

First, we need to determine the appropriate version of the springdoc-openapi-starter-webmvc-ui dependency according to the Spring Boot version. You can see the details of the version in the following link.

The compatibility matrix of springdoc-openapi with spring-boot

At this moment, I am using Spring Boot 3.4.1. So, according to the official documentation of the springdoc the version of springdoc-openapi-starter-webmvc-ui is 2.7.0.

Let's add the dependency.

Maven

Add the following dependencies to your pom.xml:

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

Gradle

If you’re using Gradle, include the dependency in your build.gradle:

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

That's it. We have integrated OpenAPI Docs and Swagger UI into our Spring Boot project.

Verifying the Swagger UI and OpenAPI doc

Open a browser, and enter the following URL:
http://localhost:8080/swagger-ui/index.html

Now, you can see the Swagger UI. Here you can see the API you have built.

To verify the OpenAPI Doc, visit the following URL,
http://localhost:8080/v3/api-docs

Customizing the paths

We can customize the default path for OpenAPI doc and Swagger UI.

To customize the default endpoints, add the following code to the application.properties file.

# Custom path for the API docs
springdoc.api-docs.path=/api-docs

# Custom path for the Swagger UI
springdoc.swagger-ui.path=/swagger-ui.html

api-docs.path: Specifies the URL path for the OpenAPI documentation.

swagger-ui.path: Sets the URL path for accessing Swagger UI.

Enhance Your Documentation (Optional)

You can enrich your API documentation with additional details using various annotations:

@Tag: Group APIs by functionality.

@Parameter: Describe query or path parameters.

@RequestBody: Document the request body format.

@ApiResponse: Document possible responses

@Schema: Describe the models

Example with Enhanced Annotations:

ProductController.java

import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@RestController
@RequestMapping("/api/v1/products")
@Tag(name = "Product Management", description = "Operations related to products")

public class ProductController {

    @Operation(summary = "Get product details", description = "Fetch details of a product by its ID.")
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200", description = "Product found",
            content = @Content(
                schema = @Schema(implementation = Product.class)
            )
        ),
        @ApiResponse(
            responseCode = "404", 
            description = "Product not found"
        )
    })
    @GetMapping("/{id}")
    public Product getProductById(@PathVariable Long id) {
        return new Product(id, "Sample Product", 100.0);
    }
}

Product.java

class Product {
        private Long id;
        private String name;
        private Double price;

        // Constructor, getters, and setters omitted for brevity.
}

Customize OpenAPI Configuration (Optional)

You can define custom metadata for your OpenAPI documentation by creating a configuration class. Here's an example:

OpenAPIConfig.java

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("API Title Example")
                        .description("API Description Example")
                        .version("API Version")
                        .contact(new Contact()
                                .name("API Contact Name")
                                .url("https://api.contact.url")
                                .email("[email protected]"))
                        .termsOfService("https://api.terms.of.service")
                        .license(new License()
                                .name("API License")
                                .url("https://api.license.url")))
                .externalDocs(new ExternalDocumentation()
                        .description("API External Documentation")
                        .url("https://api.external.documentation.url"));
    }
}

This configuration adds details such as the API title, description, version, contact information, terms of service, license, and external documentation links.

Conclusion

We can see that, adding OpenAPI docs and SWagger UI is very simple. We can easily integrate this dependency to enhance our API documentation and testing.