How to Document API in Spring Boot with Swagger and OpenAPI

To document an API in Spring Boot, use the springdoc-openapi library which generates OpenAPI documentation automatically from your code and annotations. Add the dependency, annotate your controllers with @Operation and @Parameter, and access the interactive docs at /swagger-ui.html.

Syntax

Use @Operation to describe API endpoints and @Parameter to document method parameters in your controller methods. Add springdoc-openapi dependency to your project to enable automatic OpenAPI documentation generation.

• @Operation(summary = "Description"): Describes the API method.
• @Parameter(description = "Parameter info"): Describes a method parameter.
• springdoc-openapi-ui: Dependency to generate Swagger UI.

java

dependencies {
    implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'
}

@RestController
public class MyController {

    @GetMapping("/hello")
    @Operation(summary = "Greet the user")
    public String hello(@Parameter(description = "Name of the user") @RequestParam String name) {
        return "Hello " + name;
    }
}

Example

This example shows a Spring Boot controller with documented API using @Operation and @Parameter. The springdoc-openapi-ui dependency enables Swagger UI at /swagger-ui.html where you can see and test the API interactively.

java

package com.example.demo;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@RestController
class GreetingController {

    @GetMapping("/greet")
    @Operation(summary = "Returns a greeting message")
    public String greet(
        @Parameter(description = "Name of the person to greet")
        @RequestParam String name) {
        return "Hello, " + name + "!";
    }
}

Output

When running the Spring Boot app, open http://localhost:8080/swagger-ui.html to see the API docs with the /greet endpoint documented and testable.

Common Pitfalls

• Forgetting to add the springdoc-openapi-ui dependency will prevent Swagger UI from working.
• Not annotating controller methods with @Operation or parameters with @Parameter results in minimal or no documentation.
• Using legacy Swagger 2 libraries instead of springdoc-openapi can cause compatibility issues with Spring Boot 2.6+.

java

/* Wrong: Missing dependency and annotations */
@RestController
public class BadController {
    @GetMapping("/bad")
    public String bad() {
        return "No docs";
    }
}

/* Right: Add dependency and annotations */
// Add springdoc-openapi-ui dependency
@RestController
public class GoodController {
    @GetMapping("/good")
    @Operation(summary = "Good documented endpoint")
    public String good() {
        return "Docs here";
    }
}

Quick Reference

Here is a quick cheat-sheet for documenting APIs in Spring Boot using springdoc-openapi:

Annotation/Dependency	Purpose
springdoc-openapi-ui	Dependency to enable OpenAPI and Swagger UI
@Operation	Describes an API endpoint method
@Parameter	Describes a method parameter
/swagger-ui.html	URL to access interactive API docs
@Tag	Groups endpoints under a named category

Key Takeaways

Add the springdoc-openapi-ui dependency to your Spring Boot project to enable automatic API documentation.

Use @Operation and @Parameter annotations to describe your API endpoints and parameters clearly.

Access the interactive Swagger UI at /swagger-ui.html to view and test your documented API.

Avoid legacy Swagger 2 libraries; springdoc-openapi is the modern, compatible choice.

Proper documentation improves API usability and helps frontend and backend teams collaborate.