Swagger UI API Documentation

👉 Complete Guide to OpenAPI and Swagger UI, Configuring and Generating API Docs for Spring Boot API.

What is Swagger-UI ?

In this section we will learn the simplest way to integrate Swagger UI into a Spring Boot application using the springdoc-openapi library for automatic OpenAPI specification generation. This is essential for robust, well-documented microservices.

Table of Contents

Maven Dependency

To enable OpenAPI documentation and the interactive Swagger UI, you need to add the following dependency to your pom.xml. This single dependency handles all required libraries.

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

Application Configuration

One of the greatest features of springdoc-openapi is its reliance on Spring Boot’s auto-configuration.

  • No code change required to enable swagger documentation.
  • The library automatically scans your Spring MVC controllers (@RestController) and their methods to generate the OpenAPI JSON/YAML specification at runtime.
  • This specification is then used by the bundled Swagger UI to display the API documentation.

Swagger UI

Once the application is running (e.g., on port 8080), you can access the interactive documentation via the following URLs:

  • Primary Access URL:
    • http://localhost:8080/swagger-ui.html
    • http://localhost:8080/swagger-ui
  • Alternative URL:
    • http://localhost:8080/swagger-ui/index.html
  • OpenAPI Specification:
    • http://localhost:8080/v3/api-docs
    • http://localhost:8080/v3/api-docs.yaml

Request Flow

The integration involves the springdoc-openapi library intercepting the running application context to generate the OpenAPI document, which is then served by the Swagger UI interface.

Below diagram illustrates how the components interact in your Spring Boot application.

graph TD
    A[Spring Boot Application] --> B(Spring MVC Controllers);
    subgraph Springdoc OpenAPI
        C(OpenAPI Specification Generator)
        D(Swagger UI Web Assets)
    end
    B --> C;
    C --> E[OpenAPI JSON/YAML /v3/api-docs];
    E --> D;
    D --> F[User Browser Click to open /swagger-ui.html];
    style D fill:#f9f,stroke:#333
    style F fill:#ccf,stroke:#333
    style C fill:#ddf,stroke:#333
    style A fill:#dfd,stroke:#333
    click F "http://localhost:8080/swagger-ui.html" "Swagger UI URL"

Customize API Documentation

While basic documentation is automatic, a robust microservice needs detailed descriptions. Use OpenAPI Annotations (e.g., from io.swagger.v3.oas.annotations) on your controllers and models for rich documentation.

Controller

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "User Management", description = "Operations for managing application users.")
public class UserController {

    @Operation(summary = "Get a list of all active users", 
               description = "Returns a comprehensive list of all users currently active in the system.")
    @GetMapping
    public String getAllUsers() {
        return "List of Users";
    }
}

Customize Swagger UI

You can customize the OpenAPI globally by adding properties in your application.properties or application.yml.

# application.yml
springdoc:
  # General API Information
  swagger-ui:
    path: /custom-api-docs # Change the UI access path
    disable-swagger-default-url: true
    display-operation-id: true
  info:
    title: My Secure Microservice API
    description: A robust and scalable microservice for user data processing.
    version: v1.0.1
    contact:
      name: SRE Team
      url: [https://your-company.com/sre](https://your-company.com/sre)

Security Awareness

By default, Swagger UI is accessible to everyone and when deployed in production , it’s a security risk.

Recommendation:

  • Ensure that /swagger-ui.html and /v3/api-docs endpoints are secured, restricting access to authorized personnels only.
  • This can be achieved by adding/updating rules in Spring Security to secure the endpoints.

Key Takeaways

  • The springdoc-openapi-starter-webmvc-ui is the minimalistic dependency required to enable Swagger UI.
  • It auto-configures both the OpenAPI specification generation and the Swagger UI frontend.
  • No code/config changes (like adding configuration classes or annotations) are typically needed for basic documentation.

Spring References