Saturday, July 15, 2023


I will guide you to build a simple RESTful web service using Spring Boot, and then we will generate the OpenAPI 3.0 documentation using the springdoc-openapi-maven-plugin. Step 1: Setup Spring Boot Project Create a new Spring Boot project. You can use Spring Initializr ( for easy bootstrapping of your project. For the dependencies, select: Web JPA H2 (for simplicity, we're using an in-memory database) Springdoc OpenAPI UI Step 2: Create the In src/main/resources/, add the following configuration:
Step 3: Create a simple Entity Create a Student class in your project:
import javax.persistence.Entity;
import javax.persistence.Id;

public class Student {

    private String id;
    private String name;

    // getters and setters
Step 4: Create a JPA Repository Create an interface StudentRepository that extends JpaRepository:

public interface StudentRepository extends JpaRepository<Student, String> {}
Step 5: Create a REST Controller Create a StudentController class:
import org.springframework.web.bind.annotation.*;

import java.util.List;

public class StudentController {

    private final StudentRepository repository;

    public StudentController(StudentRepository repository) {
        this.repository = repository;

    public List<Student> getAllStudents() {
        return repository.findAll();

    public Student newStudent(@RequestBody Student newStudent) {
Step 6: Generating OpenAPI 3.0 docs Add the springdoc-openapi-maven-plugin to your pom.xml:
This will generate an openapi.json file in your target directory whenever you compile your project. Now when you run your application and go to http://localhost:8080/swagger-ui.html, you should see the OpenAPI UI with your API documented. You can use the UI to send requests and see the responses. Remember to start your application before generating the documentation, because the plugin makes an actual HTTP request to the /v3/api-docs endpoint to generate the OpenAPI specification. Please be aware that as of my knowledge cut-off in September 2021, the above mentioned plugin and setup were in use. Please ensure that you're using up-to-date versions and configurations by checking the official documentation.

No comments: