From 3452eae52b92e19bb68ea75058c75b13353a8a73 Mon Sep 17 00:00:00 2001 From: Francesco Date: Wed, 11 Oct 2023 12:31:58 +0200 Subject: [PATCH] Documentation --- docs/index.html | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/docs/index.html b/docs/index.html index a80e61c..a5cb735 100644 --- a/docs/index.html +++ b/docs/index.html @@ -64,13 +64,19 @@

1. Introduction

-

This guide outlines how to install, configure and customize Spring Boot Database Admin panel. Refer to this document for troubleshooting and if you still encounter problems, please report it as an issue on Github.

+

Spring Boot Database Admin is a tool to easily build customizable database management interfaces with CRUD operations (and more!) for Spring Boot+JPA apps.

+

It does so by scanning your JPA-annotated @Entity classes and building the required functionality at runtime. With this approach it becomes trivial to integrate it, as it won't produce code that you have to integrate into your own or use as a starting point. Moreover, every time you update your classes, all changes will be reflected automatically on the web UI. +

+

On the other hand, this approach requires to interact correctly with all JPA annotations and adapt our behaviour accordingly. This is not an easy task given the large surface area of possible behaviours introduced with annotations and can sometimes introduce bugs. If you encounter problems, please report it as an issue on Github.

+ +

The rest of this guide outlines how to install, configure and customize Spring Boot Database Admin panel and, where applicable, it documents known interactions with JPA annotations.

2. Getting started

Getting started with Spring Boot Database Admin requires including it as a dependency and then performing a simple configuration step.

+

2.1 Installation

-

Since Spring Boot Database Admin is distributed on Maven, the easiest way to start is to include this dependency in your pom.xml:

+

Since Spring Boot Database Admin is distributed on Maven, the easiest way to start is to include it in your pom.xml:

 <dependency>
@@ -82,7 +88,7 @@

TIP Go to the Maven repository to retrieve the exact snippet for the latest stable release.

-

If you want the latest unstable release, you can clone the main branch of the Github repo and execute mvn install -D skipTests in the project's directory. This will install the library in your local repository, which you can then include using the same snippet as above, but replacing the version number with the one contained in the pom.xml file of the code you pulled from Github.

+

Alternatively, if you want the latest unstable release, you can clone the main branch of the Github repo and execute mvn install -D skipTests in the project's directory. This will install the library in your local repository, which you can then include using the same snippet as above, but replacing the version number with the one contained in the pom.xml file of the code you pulled from Github.

2.2 Configuration

After including the dependency, a few configuration steps are required on your end in order to integrate the library into your project.

@@ -117,16 +123,25 @@ dbadmin.modelsPackage=your.models.package,your.second.models.package

This will autoconfigure the various Spring Boot Database Admin components when your application starts.

-

If everything is setup correctly, you will see Spring Boot Database Admin confirming it in the log messages that appear when you start your application. Keep in mind that if you specify the wrong models package, it will still work but provide you an empty interface. To check, visit http://localhost:8080/admin.

+

If everything is setup correctly, you will see Spring Boot Database Admin confirming it in the log messages that appear when you start your application. Keep in mind that if you specify the wrong models package, it will still work but provide you an empty interface. Visit http://localhost:8080/admin (replace the correct port and base path with your settings) to check if everything is working correctly.

2.3 Supported features

2.3.1 Supported JPA annotations

-

The behaviour you specify with these annotations should be applied automatically by Spring Boot Database Admin as well. Keep in mind that using non-supported annotations will not necessarily result in an error, as they are simply ignored. Depending on what the annotation actually does, this could be just fine or result in an error if it interferes with something that Spring Boot Database Admin relies on.

+

The behaviours specified with these annotations should be applied automatically by Spring Boot Database Admin. Using non-supported annotations will not necessarily result in an error, as they are simply ignored. Depending on what the annotation actually does, this could be just fine or result in an error if it interferes with something that Spring Boot Database Admin relies on.

+ +

The following list documents the most significant interactions between the JPA annotations and Spring Boot Database Admin.

+
@Entity
+

Used to detect the candidate classes to scan.

+
@Column
+

Used to detect the column name and its nullability.

+
@GeneratedValue
+

When you have an @Id marked as a @GeneratedValue, you won't be asked to enter it when creating new items, as it will be automatically generated.

2.3.2 Supported field types