In this tutorial, you will learn using MapStruct for mapping/converting Java objects, JPA and Hibernate entity to DTO and vice versa. Let's get started to build a RESTful APIs example with Spring Boot and MySQL to see how MapStruct playing in the context.

What you'll need

  • JDK 8+ or OpenJDK 8+
  • Maven 3+
  • MySQL Server 5+ or Docker CE 18+

Init project structure and MapStruct

Project structure

├── src
│   └── main
│       ├── java
│       │   └── com
│       │       └── hellokoding
│       │           └── springboot
│       │               └── restful
│       │                   ├── product
│       │                   │   ├── Product.java
│       │                   │   ├── ProductAPI.java
│       │                   │   ├── ProductDTO.java
│       │                   │   ├── ProductMapper.java
│       │                   │   ├── ProductRespository.java
│       │                   │   └── ProductService.java
│       │                   └── Application.java
│       └── resources
│           └── application.properties
├── Dockerfile
├── docker-compose.yml
└── pom.xml

Setting up MapStruct

MapStruct is a Java annotation processor for generating bean mapping classes.

To set up, add MapStruct dependency into pom.xml and configure annotationProcessorPaths of maven-compiler-plugin. Full project dependencies and build plugins as below


Define JPA and Hibernate Entity, DTO, Repository, and Service



DTO, stands for Data Transfer Object, is a design pattern used for customizing/aggregating data input and output so reducing the number of call to remote API.



Using MapStruct

Define MapStruct Mapper

To using MapStruct, you have to define a @Mapper interface which declares any required mapping methods to map between entity and DTO


Here you only define simple method signatures, converting Entity to DTO, DTO to Entity, List of Entity to List of DTOs. MapStruct will generate implementation code for you during build time.

Using MapStruct on REST API

Inject your previous defined @Mapper interface into REST API and start using its methods.


Wow! what a clean REST API without writing a single mapping/converting logic :)

Config and Run

Application Configurations


hk-mysql refers to Docker Compose service defined in the below docker-compose.yml file

spring.jpa.hibernate.ddl-auto=create allows JPA/Hibernate auto create database and table schema for you.

On production environment, you may like to disable the DDL Auto feature by using spring.jpa.hibernate.ddl-auto=validate or spring.jpa.hibernate.ddl-auto=none (default). Check out this example as one of the approaches
Database Migration/Evolution Example with Flyway and JPA/Hibernate


Run with Docker

Prepare Dockerfile for Java/Spring Boot application and docker-compose.yml for MySQL Server



Type the below command at the project root directory, make sure your local Docker is running

docker-compose up  

Access to MySQL Server docker container by issuing below bash command and key in hellokoding on Enter password:

docker exec -it hk-mysql mysql -p

Run with JDK/OpenJDK, Maven and MySQL Server local

Update hk-mysql on application.properties to localhost and type the below command at the project root directory

mvn clean spring-boot:run  

Test with curl

Create a new product

curl -i -H "Content-Type: application/json" -X POST -d '{"name":"Hello Koding","description": "Simple coding examples and tutorials","price":"1"}' http://localhost:8080/api/v1/products

Find all products

curl -i http://localhost:8080/api/v1/products

Source code

https://github.com/hellokoding/hellokoding-courses/tree/master/springboot-examples/springboot-mapstruct