This blog post is about automatic documentation of OData entities. As I already explain in my previous blogs, I don’t like wasting time on tasks that can be done automatically (and in a more efficient way) by some tools. On another side, I really like, when I use some OData entities, to see a nice schema that shows detailed information and the big picture of the relation between entities.

Conclusion: let’s see if there are some ways to build documentation (schemas and diagrams) for OData entities in the SAP world

!! STOP : you’ll say…”but this already exists!”: this can be done for example via the “OpenAPI” (swagger) specification / export…

“OpenAPI” (swagger) specification…

From CAP Reference(s): https://cap.cloud.sap/docs/advanced/openapi Idea: generate openAPI json file via command line (cds compile srv –service all -o docs –to openapi –openapi:diagram)   (**) From SAP-ECC (Abap Stack) Reference(s): https://gitlab.com/geertjanklaps/abap-openapi-ui

(**): embedded in the json file, you’ll get the Yuml (https://yuml.me/) diagram code definition

Ok, but…

A diagram extractor already exists and it’s nice…but I want more details and functionalities related to the diagram processing!

The best “tool” for me to convert code definition to diagram is… Plant UML !

Let’s see if we could create a simple OData converter to Plant UML…

In this first part of this blog post, I’ll focus on the CAP flavor.

Plant-UML extractor for CAP

First of all, we need a service to give us:

• access to the data model (OData entities definition)
• the Plant-UML schema definition of our entity / entities

Here is the service definition:

Access to the service is then given via something like this:

• http://localhost:4004/v2/srv-doc-generator/getPlantUml4Entity?EntityName=Accounting.BankOperationIng

As usual, to get the same access as the runtime to your own program structures, definitions & co, the reflection API is the key (if it exists)… and luckily we have access to it from the CAP framework (see CAP services: Model Reflection API).

From the reflection API model, I will only use (this is a very basic tool/service):

I will show here a very simple and basic usage of the reflection API.

Let’s create a simple class to convert an entity definition to a Plant UML schema definition:

To access properties, let’s consider the “elements” property of the entity definition:

Same for associations:

Finally, use the class in the service implementation:

Source code: here

Insert the generated schema definition (****) to PlantUml, it will give you this:

For the information, the PlantUml code (****) looks like this:

Conclusion: diagram above is much more detailed than the one generated for Yuml…but the nice thing here is that you have a lot of directives to control orientation, colors, links…of the schema. Reflection API in CAP can be very useful in some specific scenario, don’t hesitate to use it and share ideas !

Next: Part 02 – ECC / Abap flavor

Thanks for reading,

Pierre