Swagger Like a Pro with Spring Boot 3 and Java 17

4 min readFeb 15, 2024

Greetings, Developers!

Dive into the exciting world of API development as we embark on a journey to integrate Swagger UI with Spring Boot 3.2.2 and Java 17. Swagger isn’t just any tool; it’s your gateway to creating interactive, understandable, and testable API documentation effortlessly. It’s about making your API more accessible and your development process smoother.

So, buckle up! We’re about to simplify your API adventure and make documentation a breeze. Let’s get our hands dirty and transform how you build and document APIs with Swagger and Spring Boot.

Let’s Get Rolling!

Before we jump into the deep end, let’s make sure you’re all set up. You’ll need Java 17 and Spring Boot 3.2.2 warming up in your development environment. These are the building blocks we’ll be using to construct our Swagger-infused masterpiece.

Now, let’s talk about a game-changer: the springdoc-openapi-starter-webmvc-ui dependency. This little gem is the bridge between Spring Boot and Swagger UI, making your API's documentation look like a piece of art. It automatically generates and serves your API docs in a user-friendly web interface, making your API's functionalities clear and accessible.

Spring into Action: Setting Up the Maven Dependency

Adding the springdoc-openapi-starter-webmvc-ui to your project is like inviting a superhero into your code. Simply pop open your pom.xml and include the following lines:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

This tells Maven, “Hey, we’re doing some serious Swaggering here!” It ensures that your Spring Boot 3.2.2 application gets all the Swagger goodness it needs. Remember, version harmony is key here; 2.0.2 of the Springdoc dependency plays nicely with Spring Boot 3.2.2.

Configuring Security with Swagger in Mind

In the digital world, a castle is only as good as its defenses. Similarly, an API is only as good as its security measures. But don’t worry, we won’t be sacrificing our Swagger UI’s accessibility in the name of security. It’s all about finding that sweet balance.

To do this, we’ll tweak our SecurityConfig class a bit. Think of this class as the guardian of your API kingdom. Here’s a simple guide to update your security settings:

Open your SecurityConfig class.
Add the Swagger UI’s URLs to your whitelist, just like adding VIP guests to an exclusive party list:

Each URL here serves a purpose:

/swagger-ui/**: This is your API's public face, the interactive documentation that Swagger UI provides.
/v3/api-docs/**: Think of this as the backbone of your Swagger UI, where all the API details live.

Unleashing Swagger UI

Now, let’s set the stage for your API’s grand debut by configuring the SwaggerConfig class. This class is like the director of a play, ensuring that every scene (or API endpoint) is presented perfectly.

In your SwaggerConfig class, we create the publicApi bean. It's like organizing your API's public appearances, making sure they're grouped under the "public-apis" banner for all to see
Next up, the customOpenAPI bean. This is where you get to tell your API's story, setting the title, version, and even adding some security flair with JWT

Think of these beans as your API’s resume, highlighting its best features and how to access them securely.

Final Touches and Swagger Exploration

You’re almost at the finish line! Let’s bring your API onstage:

Run your Spring Boot application. Just like starting a car, this powers up your API’s engine.
Navigate to http://localhost:8080/swagger-ui.html – this is the VIP entrance to your API documentation.
Explore! Swagger UI allows you to see your API’s endpoints, try them out in real-time, and understand their responses. It’s like having a conversation with your API.

Encourage your readers to play around with Swagger UI, experiment with different endpoint parameters, and see the immediate feedback. It’s a fantastic way to learn about your API’s capabilities and ensure it’s performing as expected.

Wrapping Up

And that’s a wrap, developers! We’ve navigated through integrating Swagger with Spring Boot, highlighting the route to better API documentation. Remember, quality documentation is essential for seamless communication between your API and its users.

I encourage you to incorporate Swagger into your Spring Boot projects, enhancing your APIs with clarity and efficiency. It’s an investment in your project’s future and usability.

As we conclude this guide, I’m eager to hear from you. Feel free to share your experiences, questions, or feedback. Let’s keep the conversation going and support each other in our development journeys.

Keep coding, keep documenting, and most importantly, keep growing. Until next time, happy coding!