Create an Entity Schema

What is an Entity Schema?: An Entity Schema defines the structure of an entity, including its properties and their types. It is used to ensure that the data for the entity is consistent and follows a defined format.
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 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 in the generated components. Starting this way makes the subsequent steps easier to understand.

ACTION E

Add Entity Schema: After creating the feature module and components, the next step is to define the entity schema in the OpenAPI file. This involves adding the base properties of the entity, which will be used to generate the API code for the frontend application.

Template: Generated Schema

Directory	`<root-of-ui-app>/src/assets/api`
File	`openapi-bff.yaml`

ACTION E in openapi-bff.yaml (excerpt)

components:
  schemas:
    ...
    <resource/entity name>:
      type: object
      required:
        - 'modificationCount'
        - 'id'
      properties:
        modificationCount:
          format: int32
          type: integer
        creationDate:
          $ref: '#/components/schemas/OffsetDateTime'
        creationUser:
          type: string
        modificationDate:
          $ref: '#/components/schemas/OffsetDateTime'
        modificationUser:
          type: string
        id:
          type: integer
        # "ACTION E: Add entity properties"

Where below properties the properties of the entity are listed.

Example

Directory	`bookstore/src/assets/api`
File	`openapi-bff.yaml`

Example: Schema of Books in openapi-bff.yaml

components:
  schemas:
    ...
    Book:
      type: object
      required:
        - 'modificationCount'
        - 'id'
      properties:
        modificationCount:
          format: int32
          type: integer
        creationDate:
          $ref: '#/components/schemas/OffsetDateTime'
        creationUser:
          type: string
        modificationDate:
          $ref: '#/components/schemas/OffsetDateTime'
        modificationUser:
          type: string
        id:
          type: string
        bookType:
          $ref: '#/components/schemas/BookType'
        bookTitle:
          type: string
        bookAuthor:
          type: string
        bookIsbn:
          type: string
        bookPrice:
          type: integer
          format: int32
        bookPublisher:
          type: string
        bookPublishedDate:
          $ref: '#/components/schemas/OffsetDateTime'
    BookType:
      type: string
      enum: [ crime, drama, fantasy, prosa, science ]

Where properties with prefix book are added to the entity Book.

Each time the OpenAPI file is changed, the API code needs to be updated to reflect these changes.
To do this, run the the following command in the terminal with the root of the UI application as current working directory.

Create API code after changing the OpenAPI file

npm run apigen

The result can be found in the generated API folder:
<root-of-ui-app>/src/app/shared/generated.