Spring Boot + Swagger: A Complete Guide to API Documentation

When building software, especially APIs (Application Programming Interfaces), clear and accurate documentation is essential. It helps other developers understand how to interact with your service: which routes are available, what data to send, and what kind of response to expect. One of the most widely used tools for API documentation is Swagger.

As backend developers, we’re deeply familiar with how APIs work. We know which requests are accepted, what responses are returned, what headers are required, which HTTP methods are used (like GET to retrieve data, POST to create, PUT to update, or DELETE to remove resources), and what various status codes mean (200 OK, 404 Not Found, 500 Internal Server Error, etc.).

But the people using our APIs, such as frontend developers, QA testers, or third-party clients, don’t always have access to that same level of understanding. Unless we clearly document our API, they’re left guessing or constantly asking for clarification. Good documentation saves time, reduces miscommunication, and makes collaboration smoother.

This is where Swagger comes in. It automatically generates interactive, user-friendly documentation based on the annotations in your code. With Swagger, users can:

• View available endpoints

• See required parameters and expected responses

• Test APIs directly in the browser

In short, Swagger makes your API easier to understand, easier to test, and easier to adopt—for everyone involved.

What is Swagger?

Swagger makes API development easier with free and powerful tools that help you and your team design and document APIs quickly and clearly, even for large projects.

API Documentation & Design Tools for Teams | Swagger

This article will walk you through how to add Swagger (which follows the OpenAPI standard) to your Spring Boot application using a popular and easy-to-use library called springdoc-openapi. This tool helps you automatically generate clean and interactive API documentation for your backend.

https://github.com/ayushstwt/product-backend.git

I have created a basic CRUD application using Spring Boot. You can clone the project from my GitHub repository.

git clone https://github.com/ayushstwt/product-backend.git

Please make sure to switch to the:

master

branch to get the base project setup. open the project in your preferred IDE such as IntelliJ IDEA or Eclipse. Make sure Java 17 or higher and Maven are installed on your system. Once everything is set up, you can run the application using the command:

./mvnw spring-boot:run

Step-by-Step: Getting Default OpenAPI Docs and Swagger UI

Step 1: Add Maven Dependency

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

Step 2: After setting up the above dependency, now we hit the URL from the browser

http://localhost:8080/v3/api-docs

and find the OpenAPI descriptions at /v3/api-docs, which is the default path

The above image shows a Swagger API documentation for a Spring Boot application. It defines a PUT API at /api/v1/products/update used to update product details. The request must have a JSON body matching the UpdateProductRequest schema. If the update is successful, the API returns a string response with status code 200. The server runs on http://localhost:8080.

if we want to show the API Data in UI format than we use The springdoc-openapi dependency already includes Swagger UI, so we’re all set to access the API documentation at

http://localhost:8080/swagger-ui/index.html

and get the result like

All the API’S which are created by us in springBoot application are now by default documented by OpenAPI

This image shows the schema for product-related API requests and responses. The UpdateProductRequest includes fields like id, productName, price, description, and imageUrl. These are used to update product details. Other schemas like CreateProductRequest and ProductResponseDTO are also listed.

The default OpenAPI configuration is already set up, so we get auto-generated API documentation. This documentation is created by OpenAPI and shows all available endpoints, request and response formats, and schemas in a clear way without writing extra code.

How to customize the OpenAPI Docs path from application.properties file?

we can customize the OpenAPI documentation path in a Spring Boot application by updating the application.properties file.

To change the default path of the OpenAPI JSON docs and Swagger UI, we can add the following properties: springdoc.api-docs.path=/custom-api-docs and springdoc.swagger-ui.path=/custom-swagger-ui. After restarting the application, your OpenAPI docs will be available at http://localhost:8080/custom-api-docs, and the Swagger UI can be accessed at http://localhost:8080/custom-swagger-ui. This is supported in SpringDoc version 2.x and above.

Open application.properties and Add the following properties

spring.application.name=product-api

server.port=8080
spring.datasource.url=jdbc:mysql://localhost:3306/productdb
spring.datasource.username=root
spring.datasource.password=ayush@123

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# Change the OpenAPI JSON docs path
springdoc.api-docs.path=/custom-api-docs

# Change the Swagger UI path
springdoc.swagger-ui.path=/custom-swagger-ui

Why We Use @Tag in Swagger/OpenAPI

The @Tag annotation is used to group APIs in Swagger UI. It helps organize endpoints by giving them a name and description. For example

@Tag(
        name = "Product Management",
        description = "APIs for managing products in the system"
)

now when we hit the this http://localhost:8080/swagger-ui/index.html endpoint than we get the following changes

This means all APIs in this controller will appear under the Product Management section in the Swagger docs. It makes the documentation cleaner and easier to understand, especially in large projects.

Why We Use @Operation in Swagger/OpenAPI?

We use @Operation to describe what an API does. It adds a short summary and a clear description to make Swagger docs easy to understand.

@Operation(
summary = "Create a new product",
 description = "Add a new product to the system"
 )

now when we hit the this http://localhost:8080/swagger-ui/index.html endpoint than we get the following changes

This helps other developers quickly know the purpose of the API without reading the full code. It makes the documentation clean and useful.

Why We Use @ApiResponses in Swagger/OpenAPI?

We use @ApiResponses to show the different responses an API can return. It helps others understand what will happen when they call the API.

@ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Product created successfully",
                    content = @Content(schema = @Schema(implementation = ProductResponseDTO.class))),
            @ApiResponse(responseCode = "400", description = "Invalid request data",
                    content = @Content(schema = @Schema()))
    })

now when we hit the this http://localhost:8080/swagger-ui/index.html endpoint than we get the following changes

It makes the Swagger docs clear and easy to follow.

Why We Use @ApiResponse in Swagger/OpenAPI?

We use @ApiResponse to define what a specific HTTP response means for an API. here @Content tells Swagger what the body content of the response (or request) will look like. and @Schema defines the structure of the data, usually by linking to a class (like a DTO).

@ApiResponse(responseCode = "200", description = "Product created successfully",
                    content = @Content(schema = @Schema(implementation = ProductResponseDTO.class))),
            @ApiResponse(responseCode = "400", description = "Invalid request data",
                    content = @Content(schema = @Schema()))

Now, when we hit the this http://localhost:8080/swagger-ui/index.html endpoint than we get the following changes

It makes the Swagger docs clear and easy to follow request and response that we get and send.

How to Test API’s in Swagger?

To test your APIs in Swagger UI, open http://localhost:8080/swagger-ui.html in your browser. You will see a list of available endpoints, such as those under the UserController. Click on an endpoint like POST /api/users, then click “Try it out” to enable input fields. Enter sample data and click “Execute” to send the request. Swagger will show the response body, status code, and headers, allowing you to easily test and debug your APIs.

You can explore the complete Swagger documentation implementation in this branch:

GitHub Branch: feat/swagger-doc

Source: Read More