Chidinma Oham

Posted on May 14

Step-by-Step Guide to Java REST APIs with OpenAPI Integration

#java #programming #software #api

A great API is one which people use. Not necessarily the one with the best design or technology behind it.

If a developer from half a world away can successfully use your API without losing their minds, you've done a great job. Good documentation makes that possible and that's where OpenAPI and Swagger come in. Their auto-generated, interactive and standardized documentation takes your API from meh to something everyone wants to build around all with a few lines of setup.

In this guide, I'll show you how to build a Java REST API using Spring Boot and integrate OpenAPI for simple and clear documentation. In five steps, you'll learn some key concepts, pro tips and how to make your API developer-friendly.

1. Setting up the Project

Let's start by creating a new project using Spring Boot and Gradle (Groovy) in IntelliJ IDEA. If you're starting from scratch, generate a Spring Boot project with these dependencies:

Spring Web: To build the REST API
Spring Data JPA: For database interaction
SQL Server Driver: To connect with SQL Server
Springdoc OpenAPI: For API documentation (more on this later)

Once your project is set up, Gradle will handle dependencies automatically.

2. Structuring the API

A clean architecture helps keep things maintainable. We're going to use this three-layered structure for the API:

Repository Layer — Manages database interactions
Service Layer — Contains business logic
Controller Layer — Handles HTTP requests

Each part has a clear responsibility and makes the API easy to extend and debug.

3. Connecting to SQL Server

A lot of people stumble here especially when starting out, so let's make sure SQL Server is properly configured. To do this:

Enable TCP/IP connections in SQL Server Configuration Manager.
Verify the SQL Server Browser service is running.
Configure your firewall to allow connections on port 1433.

To connect to the database (we're using SQL Server here), add your database credentials in the application.properties file:

spring.datasource.url=jdbc:sqlserver://localhost:1433;databaseName=mydb
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update

Spring Boot handles the connection and Hibernate takes care of ORM (Object-Relational Mapping).

💡 PRO TIP: Use environment variables for sensitive information.

4. Creating the REST API

Now that our connection is set up, we'll build a simple API to manage a user entity. This example will show the flow from request to database using the structure we defined earlier.

Entity Class

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private String email;

    // Getters and setters 
}

Repository Interface

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

Service Class

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;

    public List<User> getAllUsers() {
        return userRepository.findAll();
    }

    public User createUser(User user) {
        return userRepository.save(user);
    }
}

Controller Class

@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private UserService userService;

    @GetMapping
    public List<User> getUsers() {
        return userService.getAllUsers();
    }

    @PostMapping
    public User addUser(@RequestBody User user) {
        return userService.createUser(user);
    }
}

At this point, you can test the endpoints we created using Postman. The basic GET and POST operations for User should be functional now.

5. Integrating OpenAPI with Spring Boot

Now let's document our API in a way that's clean, interactive and self-updating. This is where Springdoc OpenAPI comes in.

If you haven't already, include this in your build.gradle file:

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

💡 PRO TIP: Run ./gradlew build or refresh Gradle so the dependencies are installed before you proceed.

Finally, to access the Swagger UI, run your application and go to: http://localhost:8080/swagger-ui/index.html

You'll see the auto-generated UI that shows our endpoints, models and request/response formats.

💡 PRO TIP: Add basic annotations and enhance your endpoints with simple descriptions.

We've just built a functional and well-structured Java REST API and made it developer-friendly with OpenAPI integration. The beauty of using Springdoc is that it doesn't require heavy setup and your documentation always stays in sync with your code.

Clean code is good. Clean, documented code? Even better.

If you're new to this or just needed a refresher, hope this helped. I'd love to hear from you — comment or reach out with questions. I reply!

DEV Community