search

jhipster / jhipster-core

JHipster Domain Language, used by JHipster UML and JDL-Studio to generate entities
Apache License 2.0
346 stars 116 forks source link

Add PlantUML JDL Support #422

Closed distributev closed 4 years ago

distributev commented 4 years ago
Overview of the feature request

PlantUML can generate many types of diagrams from text. It is like jdl-studio but with a much broader set of diagrams.

https://plantuml.com

PlantUML also offers a web service to generate & embed the diagrams into web pages "on the fly".

For instance https://www.planttext.com is using PlantUML web service for building their online UI for modelling diagrams.

https://kroki.io is another similar web service which has support for PlantUML (and many other diagram types)

Motivation for or Use Case

Being a very good tool and being long in the field PlantUML is already integrated with many existing documentation tools.

For instance AsciiDoctor has support for PlantUML - https://asciidoctor.org/docs/asciidoctor-diagram/

By writing a JDL plugin for PlantUML it will be possible to easily add JHipster JDL diagrams when writing documentation in asciidoc, markdown, etc. (through the existing PlantUML integrations)

AsciiDocFX is another (very good) tool which has built-in PlantUML support.

https://asciidocfx.com/#trueplantuml-extension

Related issues or PR
MathieuAA commented 4 years ago

Hello there!

Thanks for the time you took writing this. I'm not the one in charge of dealing with editors and IDEs though. @colameo what do you think?

colameo commented 4 years ago

Hi all, for the quick solution, just use the JHipster IDE extension for VS Code and when opening a JDL file for each model present in the workspace a corespondent UML diagram is generated automatically.

However, if you want the PlantUML text file I can add this feature in the next release but you would still need the JH IDE ...

~Serano

distributev commented 4 years ago

"if you want the PlantUML text file I can add this feature in the next release"

if you already have some work done maybe this can be wrapped as a PlantUML plugin extension.

I was thinking this can be done as some kind of PlantUML plugin so that PlantUML itself will be able to render JDL along with its existing many types of diagrams. The benefit for JHipster would be that PlantUML is already integrated into lots of documentation tools (i.e. asciidoc) and this way JDL itself will be easy to integrate into code like "livable designs" - consider when currently JHipster users need to put a model into their design documents? They need to export to PNG and add the PNG to their designs. And if JDL changes they need to update the PNG file ... - Why not put the JDL code model directly into their documents and when JDL will change their documentation will be kept in sync automatically (since JDL is used to generate the app).

PlantUML will add JHipster JDL on their home page - https://plantuml.com

"if you want the PlantUML text file I can add this feature in the next release"

colameo commented 4 years ago

if you already have some work done maybe this can be wrapped as a PlantUML plugin extension.

...need to investigate but should be feasible.

colameo commented 4 years ago

I've implemented this evening a converter called jdl2plantuml.

Usage:

java -jar ./jdl2plantuml.jar MyModel.jdl

or a list of JDL files:

java -jar ./jdl2plantuml.jar MyModel.jdl MyOtherModel.jdl

or even wildcards:

java -jar ./jdl2plantuml.jar *.jdl

Be aware that it validates also the JDL model and if there are issues it will print them out to the console.

Of course, a JDL with issues won't compile (produce) a PlantUML file (MyModel.jdl => MyModel.plantuml).

Have a look and let me know what do you think. However, as I said it's just a quick (first) solution which of course can be improved ;-)

MathieuAA commented 4 years ago

@colameo you're awesome

colameo commented 4 years ago

I've renamed this utility to JDL Bridge because I would like to add more features to it. And now it's also available as an npm package:

npm install -g jdlbridge

Usage:

    jdlbridge -plantuml|-png <path or list of JDL files with wildcards>
    jdlbridge -plantuml MyModel.jdl => produces a PlantUML text file
    jdlbridge -plantuml -png MyModel.jdl => produces a PlantUML text file and an UML diagram in PNG
    jdlbridge -plantuml MyModel.jdl MyOtherModel.jdl
    jdlbridge -plantuml -png *.jdl => selects all JDL files in a folder

Please be aware that all this is EXPERIMENTAL and I would first like to have it tested properly before spreading around... thanks!

MathieuAA commented 4 years ago

Alright then! Thanks!

MathieuAA commented 4 years ago

I'm closing this one, @colameo thanks for this! Don't hesitate to ping the twitter-crazy JHipsters so that they make the proper communication when you're ready.

pascalgrimaud commented 4 years ago

waiting you, on Twitter, @MathieuAA :)

colameo commented 4 years ago

I'm closing this one, @colameo thanks for this! Don't hesitate to ping the twitter-crazy JHipsters so that they make the proper communication when you're ready.

I've started to enhance this utility so that we can generate from JDL files a nice AsciiDoc page with comments from JDLs and PlantUML diagrams. However, need a couple of hours to finish ... I'll let you know.

colameo commented 4 years ago

I'm closing this one, @colameo thanks for this! Don't hesitate to ping the twitter-crazy JHipsters so that they make the proper communication when you're ready.

I've started to enhance this utility so that we can generate from JDL files a nice AsciiDoc page with comments from JDLs and PlantUML diagrams. However, need a couple of hours to finish ... I'll let you know.

btw: I could also generate tables from entities and even a kind of architecture overview about the generated app and deployment information etc.

distributev commented 4 years ago

Hello, @colameo what you have done seems to be exactly what is needed. I believe it is a good idea let the https://github.com/plantuml/plantuml folks knowing about your work. If they "embed" your work inside PlantUML (likely) then JDL will suddenly become available to all the places where PlantUML is currently used (VS Code, Eclipse and other IDEs, AsciiDoc documentation, etc)

Check these links

https://plantuml.com https://www.planttext.com

There are (too) many way of using PlantUML - https://plantuml.com/running

https://asciidoctor.org/docs/asciidoctor-diagram/

https://github.com/asciidocfx/AsciidocFX#plantuml-extension

https://marketplace.visualstudio.com/items?itemName=Mebrahtom.plantumlpreviewer https://plantuml.com/eclipse

colameo commented 4 years ago

I was too busy with other stuff (from time to time I need to earn some money to feed my family :smirk:). Anyways, I'm still improving this utility with other features. As already stated, at the moment I'm implementing a new feature to extract as much as possible out of JDL files and produce a spec with AsciiDoc.

Here an example produced from a with comments enriched JDL file (blog.jh).

As soon it's stable enough I will build and push a new version to npm.

(I think we should stop commenting this issue as it's closed).