DEV Community

Rizul Sharma
Rizul Sharma

Posted on

🚀 Auto-Generate Swagger Documentation for Your Java Microservice

Manually writing Swagger docs? 😓 It's time to level up your workflow and let your code generate the docs for you — automatically!

cover

If you're using Spring Boot, the best way to do this is with:

✅ Springdoc OpenAPI

🔧 What It Does

Springdoc OpenAPI is a free, open-source integration that automatically generates Swagger UI and OpenAPI 3 documentation from your Spring Boot REST APIs. No manual effort required — just annotate your controllers as usual!

🛠 How to Set It Up

1. Add Dependency in pom.xml 

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.7.0</version> <!-- use latest -->
</dependency>
Enter fullscreen mode Exit fullscreen mode

📦 Works with Maven — use the corresponding dependency for Gradle if needed.

2. Run Your Application and Access Swagger UI

Once your app is running, open your browser and visit:

http://localhost:8080/swagger-ui/index.html
Enter fullscreen mode Exit fullscreen mode

🎉 You'll see a full, interactive Swagger UI with all your API endpoints, parameters, responses, and models!

✅ What It Supports

  • REST Controllers (@RestController)
  • Mappings like @GetMapping, @PostMapping, etc.
  • Bean validation annotations (@NotNull, @Size, etc.)
  • Spring Security annotations (with extra config)
  • Custom documentation with:
    • @Operation
    • @ApiResponse
    • @Parameter

🔍 Bonus: Get Raw OpenAPI Spec

For exporting your API or generating clients:

http://localhost:8080/v3/api-docs
Enter fullscreen mode Exit fullscreen mode

Returns the OpenAPI 3 JSON spec!

✨ Example: Auto-Documented Controller 

@RestController
@RequestMapping("/api")
public class UserController {

  @GetMapping("/users")
  public List<User> getAllUsers() {
    return userService.getAllUsers();
  }

  @PostMapping("/users")
  public User createUser(@RequestBody @Valid User user) {
    return userService.createUser(user);
  }
}
Enter fullscreen mode Exit fullscreen mode

The above controller will automatically show in Swagger UI — no extra setup needed!

🙌 Final Thoughts

Using Springdoc OpenAPI is a quick win for any Java microservice project. It ensures:

  • ✅ Always up-to-date documentation
  • 🤝 Easier collaboration with frontend/backend/devops
  • 🚀 Faster onboarding for new devs
  • 🧹 Eliminates outdated manual Swagger files

🔗 Useful Links

Top comments (0)