📘 Swagger for API Documentation in Java

In the realm of modern web development, APIs (Application Programming Interfaces) play a pivotal role in enabling communication between different services and clients. With the growing number of RESTful APIs, it's essential to have clear and interactive documentation to facilitate easy consumption by developers. Swagger, now part of the OpenAPI Specification, has become the industry standard for API documentation.

In this blog post, we will explore what Swagger is, its key benefits, how to integrate it with a Spring Boot project, and how to customize it for production-grade applications.

🔍 What is Swagger?

Swagger is a set of open-source tools that help you design, build, document, and consume RESTful web services. The core of Swagger is the OpenAPI Specification (OAS), which defines a standard, language-agnostic interface to REST APIs.

🔧 Swagger Components:

Swagger Editor: Web-based editor to design and document APIs.
Swagger UI: Interactive UI for exploring APIs defined in OpenAPI.
Swagger Codegen: Generates client libraries and server stubs.
Swagger Inspector: API testing tool.

✅ Benefits of Using Swagger

Interactive API documentation
Auto-generated docs from code annotations
Standardized format for describing APIs
Client SDK generation in multiple languages
Improves collaboration between backend and frontend teams
Facilitates testing and debugging of APIs

🚀 Integrating Swagger in Spring Boot (Using Springdoc OpenAPI)

🛠️ Add Dependencies (Maven)

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

📂 Sample Controller

@RestController
@RequestMapping("/api/books")
public class BookController {

    @GetMapping("/{id}")
    public Book getBookById(@PathVariable Long id) {
        return new Book(id, "Spring Boot Essentials", "John Doe");
    }

    @PostMapping
    public Book createBook(@RequestBody Book book) {
        // Persist the book and return it
        return book;
    }
}

🔗 Access Swagger UI

Once the application runs, access Swagger UI at:

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

🧩 Annotations in Swagger

Annotation	Description
`@Operation`	Describes a single API operation
`@Parameter`	Describes operation parameters
`@Schema`	Describes the data model
`@ApiResponse`	Describes response types

Example with Annotations

@Operation(summary = "Get book by ID", description = "Returns a single book")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Found the book"),
    @ApiResponse(responseCode = "404", description = "Book not found")
})
@GetMapping("/{id}")
public Book getBook(@Parameter(description = "ID of book") @PathVariable Long id) {
    return bookService.findById(id);
}

⚙️ Customizing Swagger UI

You can customize Swagger UI using the application.yml or application.properties:

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha

🔐 Securing Swagger UI

You may want to restrict access to Swagger in production. Use Spring Security to whitelist or restrict the UI:

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .antMatchers("/swagger-ui/**", "/v3/api-docs/**").hasRole("ADMIN")
        .anyRequest().authenticated();
}

🧠 Best Practices

Avoid exposing Swagger UI in production environments.
Document all endpoints clearly with examples and descriptions.
Group APIs using tags for better categorization.
Keep your OpenAPI spec versioned and updated.
Use consistent naming conventions for paths and parameters.

🌐 Real-world Use Cases

Internal developer portals
Auto-generating client SDKs
Partner API exposure
API onboarding and testing environments

📚 Conclusion

Swagger, powered by the OpenAPI Specification, is an essential tool for API development and documentation. With minimal setup in Spring Boot, developers can expose well-documented and interactive APIs that are easy to understand and consume. By following best practices and proper annotations, you can ensure that your APIs are both accessible and secure.