If you can stand another developer tool that actually helps instead of pretending to, SpringDoc OpenAPI will generate your API spec and serve a usable Swagger UI without blood sacrifices. This guide shows how to add SpringDoc to a Maven Spring Boot project, annotate controllers for clearer docs, tweak paths when you feel picky, and run the app so you can click around instead of writing endless curl lines.

Quick setup with Maven

Add the SpringDoc UI dependency and let Maven do the heavy lifting. Replace x.y.z with the latest version from Maven Central.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>x.y.z</version>
</dependency>

The dependency exposes the OpenAPI JSON at /v3/api-docs and hosts the Swagger UI at /swagger-ui.html or /swagger-ui/index.html by default.

Annotate your controllers for better docs

Use standard Spring MVC annotations and sprinkle in OpenAPI annotations from io.swagger.v3 where it helps. The goal is readable docs not poetry.

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;

@RestController
public class PetController {

    @Operation(summary = "Find pet by id", description = "Returns a single pet")
    @GetMapping("/pets/{id}")
    public String getPet(
        @Parameter(description = "ID of the pet to fetch") @PathVariable String id) {
        return "pet " + id;
    }
}

Adding @Operation and @Parameter improves the generated schemas and saves future you from guessing what those endpoints actually expect.

Configuration tips

You can tweak where the JSON and UI live, or hide the UI in production. Put these in application.properties or application.yml depending on your preference for chaos.

# change the JSON and UI paths
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/docs

# turn the UI off in production by setting this to false in application-prod.properties
springdoc.swagger-ui.enabled=true

Another safe pattern is to keep the UI enabled only for non production profiles. For example add springdoc.swagger-ui.enabled=false in your production profile file, or use @Profile on configuration beans so documentation beans only load in dev and staging.

Keep it secure

• Do not expose the UI to the public internet unless you like strangers poking your endpoints.
• Protect docs with basic auth or an internal gateway for non development environments.
• Consider generating a static OpenAPI spec at build time if runtime exposure makes you nervous.

Run and poke the UI

Start the app the usual way.

mvn spring-boot:run
# or build then run the jar
mvn package
java -jar target/your-app.jar

Then point a browser at

• /v3/api-docs to get raw JSON
• /swagger-ui.html or /swagger-ui/index.html to launch the interactive UI

Checklist before you call it a day

• Dependency added and project builds
• Controller methods annotated for clear fields and examples
• Paths set to your taste or left alone if you like defaults
• Swagger UI disabled or protected in production

That is all you need to turn your Spring Boot endpoints into a clickable playground. It saves time, reduces guesswork, and makes debugging marginally less miserable. Now go test something and try not to break production.