Quickstart - Spring Boot
Project Dependencies
To use the unit-api with Spring Boot you need to include the following dependencies to your pom.xml/build.gradle file:
implementation("com.raynigon.unit-api:jackson-starter:1.1.7")
implementation("com.raynigon.unit-api:jpa-starter:1.1.7")
<dependency>
<groupId>com.raynigon.unit-api</groupId>
<artifactId>jackson-starter</artifactId>
<version>1.1.7</version>
</dependency>
<dependency>
<groupId>com.raynigon.unit-api</groupId>
<artifactId>jpa-starter</artifactId>
<version>1.1.7</version>
</dependency>
If you use jdbc instead of jpa or no persistence layer at all skip the jpa-starter
module.
Rest API Usage
You can declare your model like this:
public class BasicEntity {
public String id;
@JsonUnit(KilometrePerHour.class)
public Quantity<Speed> speed;
}
Jackson will now accept any quantity and convert it to the given unit. The following examples will be accepted by Jackson:
{
"id": "65bf1872-d197-4d72-9950-2b7b4d74a674",
"speed": 80
}
{
"id": "65bf1872-d197-4d72-9950-2b7b4d74a674",
"speed": "80"
}
{
"id": "65bf1872-d197-4d72-9950-2b7b4d74a674",
"speed": "80 km/h"
}
{
"id": "65bf1872-d197-4d72-9950-2b7b4d74a674",
"speed": "22.2222 m/s"
}
Every example will result in having the speed property with a value of 80 and the unit "km/h".
Jpa Entity Usage
You can declare your entity like this:
@Entity
@Table("basic_entity")
@TypeDef(
name = "quantity",
typeClass = QuantityType.class,
defaultForType = Quantity.class
)
public class BasicEntity {
@Id
@Column(name="id")
public String id;
@JpaUnit(KilometrePerHour.class)
@Column(name="speed")
public Quantity<Speed> speed;
}
You need to have the @TypeDef
annotation due to a missing feature in hibernate
(see here).
Depending on the database you are using, you need to specify the columnDefinition
property
in the @Column
annotation.
By default, the value stored in the database will be a floating-point value.
In this example the value will be saved in "km/h".
Springdoc Usage
To use the unit-api with springdoc you need to include the following dependencies to your pom.xml/build.gradle file:
implementation("com.raynigon.unit-api:springdoc-starter:1.1.7")
<dependency>
<groupId>com.raynigon.unit-api</groupId>
<artifactId>springdoc-starter</artifactId>
<version>1.1.7</version>
</dependency>
Rebuild your application and check you swagger documentation generated by springdoc.
(Usually located at http://localhost:8080/swagger-ui.html)
The Examples will now contain a value with a valid unit foreach Quantity<?>
property.