springdoc-openapi-maven-plugin

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 (https://start.spring.io/) 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 application.properties In src/main/resources/application.properties, add the following configuration:

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=password
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect

Step 3: Create a simple Entity Create a Student class in your project:

import javax.persistence.Entity;
import javax.persistence.Id;

@Entity
public class Student {

    @Id
    private String id;
    private String name;

    // getters and setters
}

Step 4: Create a JPA Repository Create an interface StudentRepository that extends JpaRepository:

import org.springframework.data.jpa.repository.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;

@RestController
@RequestMapping("/api/students")
public class StudentController {

    private final StudentRepository repository;

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

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

    @PostMapping
    public Student newStudent(@RequestBody Student newStudent) {
        return repository.save(newStudent);
    }
}

Step 6: Generating OpenAPI 3.0 docs Add the springdoc-openapi-maven-plugin to your pom.xml:

  
<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.5</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <phase>compile</phase>
            <configuration>
                <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
                <outputFileName>openapi.json</outputFileName>
                <outputDir>${project.build.directory}</outputDir>
            </configuration>
        </execution>
    </executions>
</plugin>

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.