Create an Entity Schema

What is an Entity Schema?: An entity schema defines the structure of an entity/resource, including its properties and their types. It is used to ensure that the data for the entity is consistent and follows a defined format. The schema definition follows the OpenAPI specification. This is the basis for processing feature data, e.g., for searching, displaying, and modifying it.
At OneCX, we explicitly follow an API-first approach. In practice, this means that the OpenAPI Specification file is created first, in which entities and the paths for requests/responses are described. The OpenAPI file serves as the basis for the implementation of the backend services and the frontend components.

Let’s begin by describing the entity that can be managed by generator. Starting this way makes the subsequent steps easier to understand.

ACTION E

Add Entity Schema: Second step of generating a backend service is run the generator with create-schema command. This command will create the entity schema in OpenAPI file and generate the basic logic for entity including Liquibase changelog, DAOs, controllers, entity mappers and exception mappers. Api is distinguished for external and internal api. You can run the generator with two ways to define it - by a part of command or as a model.yaml file. The first way is to run the generator with following command, where --resource flag is used to specify the name of the entity, which will be used as base for entity name and some essential application parts as following:

java -jar onecx-svc-generator.jar add-entity \
  --project ../onecx-demo-svc \
  --package org.tkit.onecx.demo \
  --entity Product \
  --fields name:String,price:BigDecimal \
  --root true \
  --build true

where root flag is used to specify if the entity is root entity, which means that it will be exposed in the API and have its own controller and service. If you want to create a non-root entity, you can omit this flag and it will be created as a nested entity.
For non-root entities, you can specify the parent entity using the --parent flag.

java -jar onecx-svc-generator/generator/target/onecx-svc-generator-1.0.0-runner.jar add-entity \
  --project ../onecx-demo-svc \
  --package org.tkit.onecx.demo \
  --entity ProductItem \
  --fields quantity:Integer,position:Integer \
  --root false \
  --api-parent Product \
  --api-field items \
  --api-parent-collection true \
  --build true

Second way is to define the entity in a model.yaml file and run the generator with following command, where --model flag is used to specify the path to the model.yaml file.

java -jar onecx-svc-generator.jar batch-model \
  --project ../onecx-demo-svc \
  --package org.tkit.onecx.demo \
  --model ../onecx-demo-svc/examples/model.yaml \
  --build true

example of model.yaml file is provided in the generator repository under examples directory.
https://github.com/onecx/onecx-svc-generator/blob/main/examples/model.yaml

entities:
  - name: Category
    aggregateRoot: false
    fields:
      - name:String

  - name: Product
    aggregateRoot: true
    fields:
      - name:String
      - price:BigDecimal
    relations:
      - category:ManyToOne:Category

In this example, two entities are defined - Category and Product. Product is defined as an aggregate root entity, while Category is not. The Product entity has two fields - name and price, while the Category entity has one field - name. Additionally, a relation is defined between Product and Category, where a product can belong to one category (ManyToOne relation). Generator is adding relation as annotation, so you can use any relation you want, generator can build relations as below: - OneToOne - OneToMany - ManyToMany - ManyToOne

+ After running the generator with either of the above commands, the entity schema will be added to the OpenAPI file and the basic logic for the entity will be generated. The generated code can be found in the src/main/java directory of the generated service.