Swagger Documentation with Spring Boot

📘 What is Swagger?

Swagger (OpenAPI) is a tool that automatically generates interactive API documentation for your REST endpoints — making it easier to test, share, and understand your APIs.

🚀 Quickstart: Swagger with Spring Boot

✅ Step 1: Add Swagger Dependencies (OpenAPI 3)

In pom.xml:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- Check for latest -->
</dependency>

✅ Step 2: Run Your App

Once the dependency is added and your Spring Boot app is running, visit:

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

or

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

You’ll see an interactive page listing all your REST endpoints! 🎉

✅ Step 3: Optional API Info (Customization)

You can customize the Swagger info using annotations:

@OpenAPIDefinition(
    info = @Info(
        title = "Student API",
        version = "1.0",
        description = "API for managing students"
    )
)
@SpringBootApplication
public class MyApp {
    public static void main(String[] args) {
        SpringApplication.run(MyApp.class, args);
    }
}

🧑💻 Example REST Controller

@RestController
@RequestMapping("/students")
public class StudentController {

    @GetMapping("/{id}")
    public ResponseEntity<Student> getStudent(@PathVariable Long id) {
        return ResponseEntity.ok(new Student(id, "Aftab", "aftab@email.com"));
    }

    @PostMapping
    public ResponseEntity<String> createStudent(@RequestBody Student student) {
        return ResponseEntity.ok("Student created!");
    }
}

 

These will appear automatically in Swagger UI.

🧠 Why Use Swagger?

  • 📖 Auto-generated API documentation
  • 🧪 Try out API endpoints directly from the browser
  • 📤 Easy to share with frontend/mobile teams
  • ✅ Great for debugging and testing
Back to blog

Leave a comment