Automatically generate UML sequence diagram according to text (draw.io format)

1. Preface

There are some tools that can automatically generate text UML Sequence diagram , Such as PlantUML（https://plantuml.com/zh/）、Mermaid（https://mermaid-js.github.io/mermaid/） etc. . But there are some inconveniences , For example, activation needs to be specified manually 、 The grammar is complex , It's not easy to remember 、 Some functions are used less frequently 、 It is not convenient to continue editing manually 、 The display style is similar to the common UML Different sequence diagrams, etc .

Therefore use Java Developed the following automatic generation based on text UML Sequence diagram tool , Activation can automatically generate 、 Grammar is simple and easy to remember , Support most UML Functions of sequence diagram 、 Generate draw.io Format file , You can continue editing 、 The display style is similar to the common UML Sequence diagram is consistent .

This tool generates UML The terms and styles related to the sequence diagram refer to https://www.uml-diagrams.org/sequence-diagrams.html, Supported elements include ： Lifeline （Lifeline）、 Activate （Execution/Activation）、 news （Message）.

The current project can be used for Java Code auto generation UML Sequence diagram , May refer to https://github.com/Adrninistrator/gen-java-code-uml-sequence-diagram.

2. Update instructions

• 0.1.0

It supports calculating the required height according to the message text , It is no longer necessary to manually specify a unified fixed height

• 0.1.1

Check whether the input file code is UTF-8-BOM

3. Example

The following is generated by this tool draw.io Format UML Sequence diagram ：

Generate above UML The text of the sequence diagram is as follows ：

>><font color="#0000ff"><u> This is a description </u></font><br>end~ This is a link 
@<font style="font-size: 17px" face=" Juvenility " color="#000000"><b><i> Small <br> bright </i></b></font> as xm
@ Dad 
@ Mom  as mm
@ teacher 
@ Ask for leave <br> System  as qjxt
xm=>xm:<strike> I don't want to go to school today </strike>
xm-> Mom :<font style="font-size: 18px" face=" Microsoft YaHei " color="#000000"> Mom, I don't want to go to school today <br> I don't feel well </font>
xm=>mm:			<b> Mom, I'm not feeling well today <br> Help me find a teacher to ask for a leave </b>
mm=> teacher : Xiao Ming is not feeling well today <br> I want to take a leave 
 Mom <= teacher :<font style="font-size: 16px" face=" Juvenility " color="#0000ff"><b><i> Wait a moment, I'll check the records <br> I will reply to you later </i></b></font>
xm<= Mom :<u> The teacher said to wait for a while </u>

 teacher => teacher : Let me see Xiao Ming's leave record ~https://www.baidu.com
 teacher =>qjxt: Query Xiao Ming's leave record 
 teacher <= Ask for leave <br> System : Return the data <br> Leave this year 0 Time 
 teacher => Mom : Then let him rest for a day 
 teacher <= Mom : Thank you, teacher 

 Mom ->xm: The teacher agreed to your leave 

By default, the sequence number will be automatically added to each message , It can be closed through the configuration described later .

Move the mouse over the lifeline or activate , The description of the corresponding lifeline will be displayed , It is convenient to view when the sequence diagram is long .

4. Generate from text file UML Sequence diagram

The code address of this tool is ： https://github.com/Adrninistrator/uml-sequence-diagram-drawio/ .

4.1. Usage mode

The operating system using this tool requires JDK, And configure the corresponding directory in the environment variable .

4.1.1. Execute... From the command line

You can download this tool from the following address and extract ：

https://github.com/Adrninistrator/uml-sequence-diagram-drawio/releases/

stay Windows Environment execution , You can execute the following commands on the command line , Parameters 1 Is the text file path （ You can drag and drop files into the command line window in Explorer ）：

run.bat [ Text file path ]

stay Windows Environment execution , You can also drag a text file to run.bat Execute on the icon , Easier to operate .

stay Linux Wait for the environment to execute , You can execute the following commands on the command line , Parameters 1 Is the text file path ：

sh run.sh [ Text file path ]

After execution , The corresponding... Will be generated in the directory where the text file path is located draw.io Format UML Sequence diagram file .

4.1.2. stay Java Implemented in the project

stay Java When executing this tool in a project , This tool can be introduced in the following ways ：

• Gradle

testImplementation 'com.github.adrninistrator:uml-sequence-diagram-drawio:0.1.1'

• Maven

<dependency>
  <groupId>com.github.adrninistrator</groupId>
  <artifactId>uml-sequence-diagram-drawio</artifactId>
  <version>0.1.1</version>
  <type>provided</type>
</dependency>

perform com.adrninistrator.usddi.runner.RunnerGenUmlSequenceDiagram class ,generate() Method , According to the specified text file , Generate corresponding draw.io Format UML Sequence diagram file .

4.2. Input text requirements

4.2.1. Enter text keywords

The following keywords are used to specify the description ：

>>

The following keywords are used to specify the name of the lifeline ：

@
as

The following keywords are used to specify messages ：

=>
<=
->
:

The following keywords are used to specify links to descriptions or messages ：

~

The following keywords are used to specify comments ：

#

4.2.2. Enter text format

4.2.2.1. Description format

Description refers to the text at the top of the sequence diagram for explanation , Not associated with sequence diagram , For illustrative purposes only .

• >>description

Use “>>description” Format specifies the description ,“description” For the content of the description , Any content can be specified ;

The description needs to be specified at the beginning of the input text , Only one description can be specified , Or not .

You can use HTML The label sets the style that describes the content , Such as line feed, etc , Refer to the following content .

4.2.2.1.1. Link format

• >>description~link

Use “~link” Format specifies the link corresponding to the description ,“link” For linked content ;

Click to specify the description of the link , The corresponding link will be displayed , As shown below ：

Link content can be specified as general text , You can also specify URL Or file path （file://）, As shown below ：

file://C:\Windows\System32\calc.exe
file://C:\Windows\system.ini
https://www.baidu.com

When the link content is specified as URL when , When you click the link, the default browser will be used to open the corresponding URL;

When the link content is specified as the file path , When clicking the link, the default software of the corresponding file format will be used to open the file , If no default software is specified for the corresponding file format , Will not open , You have to set it .

4.2.2.2. Lifeline format

What precedes the input text （ If there is a specified description , After the description ）, Use the following format to specify lifelines , The order in which lifelines appear in the input text （ From the top down ） And in UML The display sequence in the sequence diagram （ From left to right ） Agreement .

• @name

Use “@name” Format specifies lifeline ,“name” Is the name of the lifeline ;

• @name as alias

To simplify the name of lifeline , You can use “@name as alias” Format specifies the name of the lifeline , And alias ,“alias” Alias for lifeline ;

4.2.2.3. The message format

What follows in the input text , Specify the message using the following format , The order in which messages appear in the input text （ From the top down ） And in UML The display sequence in the sequence diagram （ From the top down ） Agreement .

Following “~L” Optional data , If you do not need to specify a link for the message, you do not need to specify .

• x=>y:m~L

Use “x=>y:m~L” Format specifies the synchronization request message ;

“x” Is the name or alias of the starting lifeline ,“y” Is the name or alias of the destination lifeline ,“m” For the message content ;

• x<=y:m~L

Use “x<=y:m~L” Format specifies the return message ;

“y” Is the name or alias of the starting lifeline ,“x” Is the name or alias of the destination lifeline ,“m” For the message content ;

The synchronization request message and the return message need to appear in pairs in the correct location ;

• x=>x:m~L

Use “x=>x:m~L” Format specifies the self calling message ;

“x” Is the name or alias of lifeline ,“m” For the message content ;

• x->y:m~L

Use “x->y:m~L” Format specifies asynchronous messages ;

“x” Is the name or alias of the starting lifeline ,“y” Is the name or alias of the destination lifeline ,“m” For the message content ;

4.2.2.3.1. Link format

In the above message content “L” For links , You don't specify , The format has been described above ;

An example of specifying a link for a message is as follows ：

4.2.2.4. Annotation format

In the input text , With “#” The first line represents the comment .

4.2.2.5. The sequence diagram starts a new partial format

Sometimes it may be necessary to show sequence diagrams of multiple different parts in a sequence diagram , For example, in part 1 The initial starting point of the message in corresponds to the lifeline 1, In part 2 The initial starting point of the message in corresponds to the lifeline 2, under these circumstances , One or more blank lines can be specified between messages in each section , As shown below ：

 part 1 news 
 part 1 news 
...
 part 1 news 

 part 2 news 
 part 2 news 
...
 part 2 news 

4.2.3. Enter text encoding

The input text file code needs to be UTF-8.

4.2.4. Requirements for message sequence

This tool controls the processing of various messages through the stack , Therefore, the message order specified in the text needs to meet certain requirements , Otherwise, the final sequence diagram cannot be generated .

When processing the synchronization request message , The current synchronization request message will be put on the stack

When processing the return message , Will push the message at the top of the stack

When dealing with self calling messages and asynchronous messages , There will be no inbound or outbound processing

For the destination of asynchronous messages , It is not supported as the starting point of the next message .

4.3. Parameter configuration

4.3.1. Position related parameters

Location related parameters are in the configuration file “~usddi_conf/position.properties” It is specified in , As shown below ：

Parameter name	Parameter function	Is it allowed to be empty	The default value is
lifeline.center.horizontal.spacing	The horizontal spacing of the middle point of the lifeline	Non empty	nothing
lifeline.box.width	Box width of lifeline	Non empty	nothing
lifeline.box.height	The height of the lifeline's box	Non empty	nothing
message.vertical.spacing	news （ And between and lifeline ） Vertical spacing	Non empty	nothing
self.call.horizontal.width	The horizontal width of the self calling message	Non empty	nothing
activation.width	Width of activation	Non empty	nothing
parts.extra.vertical.spacing	Additional vertical spacing between two parts	Optional	0

The height of the message depends on the size of the message font and the number of message lines （<br> On behalf of the line ） calculated , There is no need to manually specify

4.3.2. Examples of location related parameters

An example of position related parameters is shown below ：

4.3.3. Style related parameters

The style related parameters are in the configuration file “~usddi_conf/style.properties” It is specified in , As shown below ：

Parameter name	Parameter function	Is it allowed to be empty	The default value is
message.auto.seq	Automatically add sequence numbers to messages	Optional	yes
line.width.of.lifeline	Line width - Lifeline	Optional	1
line.width.of.activation	Line width - Activate	Optional	1
line.width.of.message	Line width - news	Optional	1
line.color.of.lifeline	line color - Lifeline	Optional	black
line.color.of.activation	line color - Activate	Optional	black
line.color.of.message	line color - news	Optional	black
box.color.of.lifeline	Box background color - Lifeline	Optional	white
box.color.of.activation	Box background color - Activate	Optional	white
text.font.of.lifeline	Text font - Lifeline	Optional	Helvetica
text.font.of.message	Text font - news	Optional	Helvetica
text.size.of.lifeline	Text size - Lifeline	Optional	12
text.size.of.message	Text size - news	Optional	12
text.color.of.lifeline	Text color - Lifeline	Optional	black
text.color.of.message	Text color - news	Optional	black

Color related parameters , Should be RGB Color hexadecimal form , namely “#xxxxxx”, Such as “#00ff00”;

Parameters related to text font , The name of the font should be specified , Such as “ Song style ”、“Times New Roman”;

Parameters related to line width , Support integer or decimal ;

Parameters related to text size , Supports integers .

4.4. Name a lifeline 、 The message content text specifies the style

The above style related parameters are for a UML Unified parameter configuration in the sequence diagram , When you need to name a lifeline 、 When the message content text is individually styled , It can be realized in the following way ：

4.4.1. Text font 、 size 、 Color

Text font 、 size 、 Color can be passed HTML Medium font Label to set , As shown below ：

<font face=" Song style " style="font-size: 18px" color="#ff9999" >xxx</font>

• Text font

<font face=" Song style ">xxx</font>

• Text size

<font style="font-size: 18px">xxx</font>

• Text color

<font color="#ff9999" >xxx</font>

4.4.2. In bold 、 Italics 、 Underline 、 Delete line

The words are bold 、 Italics 、 Underline 、 Strikethrough HTML Set the label in , As shown below ：

• In bold

<b>xxx</b>

• Italics

<i>xxx</i>

• Underline

<u>xxx</u>

• Delete line

<strike>xxx</strike>

• Multiple styles

<b><i><u><strike>xxx</strike></u></i></b>

Also specify the text font 、 size 、 Color , And bold 、 Italics 、 Underline 、 When deleting a line , As shown below ：

<font face=" Song style " style="font-size: 18px" color="#ff9999" ><b><i><u><strike>xxx</strike></u></i></b></font>

4.4.3. Word wrap

When you need to wrap text , Use the following as line breaks ：

<br>

5. stay Java Generated in the project UML Sequence diagram

Call above Java component-provided RunnerGenTextFile4USD class , Can be generated for generating UML Text file of sequence diagram , Then generate according to the text file UML Sequence diagram , The methods provided by this class are described below ：

Method name	function
init	initialization
writeDescription	Setup description
writeComment	Add notes
addReqMessage	Add synchronization request message
addRspMessage	Add a return message
addSelfCallMessage	Add self calling message
addAsyncMessage	Add asynchronous request message
write2File	Write the added data to the file

In the use of RunnerGenTextFile4USD Class time , You need to call init Method , Specify the path of the text file to be generated , Then add comments or messages as needed , Last call write2File Method writes the added data to the file .

RunnerGenTextFile4USD An example of using the class is as follows , May refer to test.usddi.gen_text_file.TestGenTextFile4USD class .

String filePath = "test-" + System.currentTimeMillis() + ".txt";
System.out.println(filePath);

RunnerGenTextFile4USD runnerGenTextFile4USD = new RunnerGenTextFile4USD();

try (BufferedWriter writer = runnerGenTextFile4USD.init(filePath)) {
    
    //  Setup description 
    runnerGenTextFile4USD.writeDescription("description", "descriptionLink");

    //  Add notes 
    runnerGenTextFile4USD.writeComment("111");
    runnerGenTextFile4USD.writeComment("222");
    runnerGenTextFile4USD.writeComment("333");

    //  Add different types of messages 
    runnerGenTextFile4USD.addReqMessage("a", "b", " request 1");
    runnerGenTextFile4USD.addRspMessage("a", "b", " return 1");
    runnerGenTextFile4USD.addSelfCallMessage("a", " Self calling 1<br>aaa");
    runnerGenTextFile4USD.addAsyncMessage("a", "c", " Asynchronous requests 1<br>bbb");

    //  Write the added data to the file 
    runnerGenTextFile4USD.write2File();

    //  Generate from text UML Sequence diagram file 
    new RunnerGenUmlSequenceDiagram().generate(filePath, filePath + USDDIConstants.EXT_DRAWIO);
} catch (Exception e) {
    
    e.printStackTrace();
}

6. Generated .drawio How files are used

6.1. Open it directly .drawio file

You can download it from the following address draw.io Desktop software ：

https://github.com/jgraph/drawio-desktop/releases

This tool generates .drawio The file can be used draw.io The software opens and edits .

6.2. Copy .drawio Of documents XML Content

Copy the .drawio Of documents XML Content , stay draw.io Desktop version or web version , open “ other -> Edit the drawing ”, or “Extras->Edit Diagram” menu , You can paste it into the currently open draw.io In file .