Create UML diagrams using PlantUML and Integrate with Readme

What is UML diagram?

A UML diagram is a diagram based on the UML (Unified Modeling Language) with the purpose of visually representing a system along with its main actors, roles, actions, artifacts or classes, in order to better understand, alter, maintain, or document information about the system.

What is PlantUML?

PlantUML is an open-source tool allowing users to create diagrams from a plain text language. Besides various UML diagrams, PlantUML has support for various other software development related formats (such as Block diagram, Gantt chart, Mind map and etc…), as well as visualisation of JSON and YAML files.

What is .MD file?

MD files are the extensions of files created Markdown language software. Markdown is a lightweight markup language intended for one purpose, to be used to format text on the web with plain text formatting syntax.

Create UML diagrams using PlantUML

With help of PlantUML components we can create the following different kind of diagrams

• Sequence diagram
• Usecase diagram
• Class diagram
• Object diagram
• Activity diagram
• Component diagram
• Deployment diagram
• State diagram
• Timing diagram

We can simply create a new file with the extension of .pu/.puml. If we using Visual studio code we can use PlantUML extension which provides helpful features like preview our UML diagrams, export diagrams to PDF/image, format our UML code etc…

Sample Sequence PlantUML diagram:

@startuml ClientServerCommunication
Client -> Server: Authentication Request
Server --> Client: Authentication Response
Client -> Server: Another authentication Request
Server <-- Client: Another authentication Response
@enduml

ClientServerCommunication is name of the diagram. When we create some SVG/image it will be created in the name of ClientServerCommunication.

Preview:

For example, we can use this kind of diagrams to maintain complex work flow of our system/Architecture of the platform etc... so this will help team to understand the system/platform well that they working on.

Since this can be done using UML, If there is any change in the system work flow or Architecture, it will be very easy to edit the existing diagram and keep updated as the system/platform.

To know more about PlantUML components visit https://plantuml.com/

Generate SVG from PlantUML file

To generate SVG from PlantUML file, need to have plantuml.jar. We can download this from https://plantuml.com/download.

java -jar plantuml.jar -v -tsvg <file_name>.pu

The above command will generate the equivalent SVG of the UML diagram. Which will be later integrated with README file.

Integrate UML diagram with Readme file and Automate the SVG creation

Create a new directory and initialise it with a GitHub repo.

The folder structure something like below

Create a GitHub workflow file (generate.yml) with the following code.

name: Generate svg from uml
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Generate Diagrams
run: java -jar plantuml.jar -v -tsvg "**.pu"
- name: Commit Diagrams
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add .
git commit -m "Update generated diagrams" || exit 0
- name: Push Diagrams
uses: ad-m/github-push-action@master
with:
github_token: ${{ github.token }}

README.MD file something like the below

# UML Diagrams
### Client Server Communication
![](./ClientServerCommunication.svg)

README.MD preview

So, Whenever we push the changes to GitHub, the Github workflow itself generate the updated UML diagrams from the plantUML file and updated it in the Github repo. In this way you will always see the latest UML diagram in our Readme file.

Thanks for Reading!

Reference:

• https://plantuml.com/
• https://gist.github.com/thedmeyer/8b50362ae71ecbadabb17f8683c70ece
• https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml