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)