Why you should care

Testing and documenting your REST API should not be a full time hobby. SpringDoc connects Spring Boot with OpenAPI and gives you a Swagger UI that lets you poke endpoints from a browser without writing curl scripts and crying. This guide shows how to add SpringDoc to a Maven project and use Swagger UI to test and document Java REST APIs.

What you need

• Java 11 or newer
• Maven
• A Spring Boot app with controllers

Step by step

1. Add the SpringDoc dependency

   Add the springdoc openapi ui dependency to your pom file and let Maven do its magic.

   <dependency>
     <groupId>org.springdoc</groupId>
     <artifactId>springdoc-openapi-ui</artifactId>
     <version>1.6.15</version>
   </dependency>

2. Configure package scanning if needed

   SpringDoc usually auto detects your controllers. If your controllers live in odd packages set a property or add a small config bean.

   # application.properties example
   springdoc.packagesToScan=com.example.controllers

   Or register a bean that configures the scanner when auto detection fails.

3. Run the app

   Start it from your IDE or run mvn spring-boot run and wait for the glorious startup messages. SpringDoc will expose the OpenAPI JSON and the Swagger UI.

4. Open Swagger UI and try endpoints

   Visit the UI at /swagger-ui.html or at /swagger-ui/index.html depending on the version. The raw OpenAPI JSON lives at /v3/api-docs. Use the Try it button to send requests right from the browser and inspect headers and payloads.

   • Fill in example JSON and watch how status codes and responses behave
   • No more guessing or sculpting curl commands in the dark

5. Harden the docs for production

   Documentation is helpful but not always something you want public. Add Spring Security rules or use Spring Boot actuator to limit access. Expose docs only in staging or require basic auth for production access.

Quick tips

• Use the latest springdoc openapi ui release for security fixes and features
• Annotate controllers with request and response schemas to improve documentation
• Keep example payloads realistic to speed up testing

Summary

Adding SpringDoc to a Maven based Spring Boot project is mostly dependency add run and browse. You get a friendly Swagger UI to test REST APIs and machine readable OpenAPI JSON for docs and tooling. Go forth and document responsibly.