Swagger UI Integration in Spring Boot 3
Transcript:
How can we document APIs so that even juniors understand what's what? The answer is open API and swagger. In this video, you will learn how to turn your Spring Boot API into a beautiful browsable user interface using Open API specification and swagger. So stay with me and by the end of this video, you will be able to document your Spring Boot API like a pro. Ready, steady, go.
Okay, let's get one thing straight. Open API and swagger are not the same thing. Open API is a specification. Basically, it is a standardized way of describing your API. We can say that it is like a blueprint that explains how your HTTP API works in a language agnostic way. Humans can read it, computers can read it. No need for extra documentation and no need to dig into the source code. When you create Open API documents, you write them in YAML or JSON format. Pretty straightforward, right? Now, let's talk about Swagger. Swagger is a toolkit. It helps developers create, edit, and use API according to the Open API specification. And here's the awesome part. With Swagger, you don't have to manually write the API documentation anymore. The tool can actually read through annotations in your code and generate documentation automatically. And there's more. Swagger provides a user interface that helps to create interactive API documentation. It means that developers can test APIs right in the browser.
So remember, Open API is a specification. Swagger is a toolkit that helps to create documentation and view it through the user interface according to the open API specification. Swagger is useful for all team members. Developers can easily navigate through someone else's code. Front end can see what fields the API has. Testers understand what and how to test. And newbies can hit it off more quickly. So next time somebody asks, "Does your code support open API and Swagger?" What they really mean is, "Can I understand your API without crying?" Now that we know what Swagger and Open API are, it's time to plug them into your Spring Boot project with literally one dependency. All right, friends. Here's the deal.
In 2025, we don't use Spring Fox. It is outdated and not supported by Spring Boot 3. Instead, we use Spring Doc Open API. It is modern, actively supported and generates API documentation according to the Open API version 3. So add one dependency to your pom.xml or build Gredle file and that's it. One dependency to rule them all and in documentation bind them. Now that we have added the dependency, let's see what Open API and Swagger can give us out of the box. The Open API documentation is built when we run our project. Simply run your Spring Boot project and go to localhost 8080 version 3 API docs. Well, that's the default way. And here it is, the documentation in JSON format. Then open localhost 8080 Swagger UI index html. Boom. Swagger UI. Even without annotations, we have basic documentation. The tool picks up your controllers automatically. And that's the power of Spring Doc. And yes, I'm running this on Liberica JDK21 recommended by Spring fast and cloud ready. All right, but to really make our docs powerful, we need to add some annotations. Let's go.
Swagger UI already works, but we want more. We want the description of methods, parameters, API responses, and so on. Here is our basic setup, employee controller. Let's look at some key annotations. With the operation annotation, you can provide additional information about the method such as summary and description. The tag annotation is applied at class or method level. You use it to group the APIs in a meaningful way. The parameter annotation can be used on a method parameter to define the parameters. It can be data on parameter purpose or whether this parameter is mandatory or not. And here's how it looks in Swagger UI.
The API responses annotation helps to add information about the responses for the given method. Each response is specified with API response. Of course, you don't have to annotate every single method or field. just focus on what really matters. You know, it just came to me without annotations, your Swagger UI is like a movie in a foreign language that you don't know without subtitles. Looks pretty. You get the general picture, but no idea what's going on. And here's the complete result. Looks good, right?
Now, let's polish it off with some metadata. It's time to give your API a name, a face, and a business card. Create an open API configuration class and annotate it with configuration. This class will hold the information about your API, title, description, version, license, and so on. Use special classes from the Swagger library such as open API, info, contact, and others to define these parameters. This way you can show the world that this is a serious project, not some weekend experiment.
Some advanced tips. Tip number one, group and version your APIs. One swagger UI for all endpoints is not really convenient, especially if you have a complex monolith or microservices. You don't want authentification V1 beta internal thingy in one file, right? Luckily, Swagger allows you to group endpoints and version them. You can classify controllers by groups or versions, for instance, V1, V2, admin, public, and so on. You can use open API definition annotation to define the tags. These tags are used to visually separate your API into logical groupings like modules. For instance, we can define tags that represent the modules of your API and then assign those tags to controllers or endpoints. If you want true separation by version like Swagger UI for each version, use a grouped open API bins. This creates separate tabs for Swagger UI for version one and version two. Now, let's make sure that your beautiful Swagger UI doesn't accidentally leak APIs into the public. A great API deserves a beautiful UI. But not everybody should see that.
So, don't be that team member that accidentally leaks internal API into the pro. Oh my god. What can we do to protect our API? Well, first you can limit access to it through Spring Security and access based roles. For instance, in your security config class, make swagger UI HTML accessible only to users with admin role. Secondly, you can use profile deaf annotation to load Swagger UI only in the deaf environment. It disables swagger bins in production automatically. So update your application.properties file like that and when running with the profile pro this config will be automatically skipped. No swagger bins will be created. Thirdly you can disable swagger endpoints in application pro.properties file completely. So do whatever suits your project best. Wrap swagger in security. limit it to deaf environment or turn it off completely. But don't ignore this. You have unlocked many powerful tools Swagger has to offer. Let's wrap it up. Let's take a second and appreciate how far we have gone in just one video from zero to a fully documented, secure, and stylish API with a couple of annotations and no pain.
Drop a comment if you have any questions or you want me to discuss some other topic like more advanced swagger usage or open API integration with Postman. Like, comment, and subscribe for cleaner code, clever tools, and more Java powered tutorials.
