API documentation using openAPI, swagger-ui

💡 In this section we will cover 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

• 🧭 Table of Contents
• 🛠️ Maven Dependency Setup
• ⚙️ Automatic Configuration
• 🔗 Accessing the Swagger UI
• 🏗️ Conceptual Architecture
  • 🖼️ Architecture Diagram
• ✨ Engineering Insights \& Next Steps
  • 1. Customizing the Documentation
    • Example POC Code Snippet (Java Controller)
  • 2. Configuration Customization
    • Example Configuration Snippet (YAML)
  • 3. Security Awareness
• 🔑 Key Takeaways
• 📖 References

🛠️ Maven Dependency Setup

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.

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

⚙️ Automatic 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.

🔗 Accessing the 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 (or simply http://localhost:8080/swagger-ui)
• Alternative URL:http://localhost:8080/swagger-ui/index.html
• OpenAPI Specification URL (JSON):http://localhost:8080/v3/api-docs
• OpenAPI Specification URL (YAML):http://localhost:8080/v3/api-docs.yaml

🏗️ Conceptual Architecture

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.

🖼️ Architecture Diagram

This 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"

✨ Engineering Insights & Next Steps

1. Customizing the 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.

Example POC Code Snippet (Java 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";
    }
}

2. Configuration Customization

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

Example Configuration Snippet (YAML)

# 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)

3. Security Awareness

Improvement Suggestion: By default, Swagger UI is accessible to everyone and in a production microservice, it's a security risk.

• Actionable Step: Implement Spring Security to secure the /swagger-ui.html and /v3/api-docs endpoints, restricting access to authorized personnel only (e.g., developers, QA).

🔑 Key Takeaways

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

📖 References

• springdoc-openapi GitHub:https://github.com/springdoc/springdoc-openapi/blob/main/springdoc-openapi-starter-webmvc-ui
• springdoc Official Documentation:https://springdoc.org/#getting-started