PlantUML

Resources

• PlantUML
  • Visualize JSON
  • Sequence diagrams
  • Component diagrams
• Create diagrams with code using Graphviz
• Hitchhiker’s Guide to PlantUML
• PlantUML - real world examples
• Graphviz visual examples

Component diagrams

Shapes

@startuml
actor actor
agent agent
artifact artifact
boundary boundary
card card
circle circle
cloud cloud
collections collections
component component
control control
database database
entity entity
file file
folder folder
frame frame
interface interface
node node
package package
queue queue
rectangle rectangle
stack stack
storage storage
usecase usecase
hexagon hexagon
label label
person person
@enduml

Components have a shorthand: [X] is shorthand for component X.

Tree

More information can be found at https://plantuml.com/creole (CTRL+F “tree”).

@startuml
skinparam titleFontSize 14

title
  Fieldset
  |_ **Screen**
    |_ **Group**
      |_ **Field**{label=<color:green>"Listing title"</color>, component=<color:green>"text_input"</color>}
      |_ **Field**{label=<color:green>"Category"</color>, component=<color:green>"category_picker"</color>}
      |_ **Field**{label=<color:green>"Photo"</color>, component=<color:green>"photo_picker"</color>}
    |_ **Group**{title=<color:green>"About the item"</color>}
      |_ **Field**{label=<color:green>"Condition"</color>, component=<color:green>"single_picker"</color>}
      |_ **Field**{label=<color:green>"Price"</color>, component=<color:green>"single_picker"</color>}
      |_ **Field**{label=<color:green>""</color>, component=<color:green>"numeric_input"</color>}
      |_ **Field**{label=<color:green>"Description"</color>, component=<color:green>"text_input"</color>}
      |_ **Field**{label=<color:green>"Brand"</color>, component=<color:green>"single_picker"</color>}
      |_ **Field**{label=<color:green>"Size"</color>, component=<color:green>"single_picker"</color>}
    |_ **Group**{title=<color:green>"Optional details"</color>}
      |_ **Field**{label=<color:green>"Colour"</color>, component=<color:green>"single_picker"</color>}
      |_ **Field**{label=<color:green>"Chest"</color>, component=<color:green>"numeric_input"</color>}
      |_ **Field**{label=<color:green>"Length"</color>, component=<color:green>"numeric_input"</color>}
      |_ **Field**{label=<color:green>"Multiple quantities"</color>, component=<color:green>"checkbox"</color>}
end title

@enduml

Aliases

The as keyword defines aliases. This is useful if a component has a long name and you plan on reusing the component in your diagram.

@startuml
[/api/1.1/user/roles/] as RolesAPI
[foo-service] -> RolesAPI
[bar-service] -> RolesAPI
@enduml

Links and arrows

Links between elements are made using combinations of dotted line (..), straight line (--), and arrows (-->) symbols.

Double dashes (or dots) orient the link vertically while a single dash orients the link horizontally.

@startuml
[A] -> [B]
[B] .> [C]
[C] --> [D]
@enduml

Arrow labels

Use : <label> as a suffix to add labels to arrows and relationships between objects.

@startuml
[foo-service] -> [bar-service] : DoSomething RPC
@enduml

Stereotypes or object annotations

Stereotypes can be thought of as an annotation within an object. It is specified using << and >>.

@startuml
queue "events-v1" <<kafka topic>> as MessageQueue
[foo-service] -> MessageQueue : publish event
@enduml

Notes

You can use the note left of, note right of, note top of, note bottom of keywords to define notes related to a single object.

@startuml
note left of HTTP : Web Service only

note right of [First Component]
  A note can also
  be on several lines
end note

HTTP - [First Component]
@enduml

Grouping components

You can use several keywords to group components and interfaces together: package, node, folder, frame, cloud, database.

@startuml
package "Foo service" {
    [First component] as foo.A
    [Second component] as foo.B
}

database "foo-db" {
    [some table] as foo.table.A
    [another table] as foo.table.B
}

foo.A --> foo.table.A
@enduml

Colors

Colors can be applied using a variety of syntax. One method is <color:red>Text</color>. See https://plantuml.com/color for more information.

@startuml
colors
@enduml

Comments

@startuml
' This is a comment

/' This is a
block comment
'/
@enduml

Emphasized text

@startuml
component Foo
note left
  This is **bold**
  This is //italics//
  This is ""monospaced""
  This is --stricken-out--
  This is __underlined__
  This is ~~wave-underlined~~
end note
@enduml

Sequence diagrams

Documentation: https://plantuml.com/sequence-diagram

Basic example

• -> renders an arrow between participants.
• --> renders a dotted arrow. I like to use this to denote returns.
• ++ activates a bar on the target participant.
• -- deactivates a bar on the source participant.
• --++ can be used to mix activations and deactivations.
• \n can be used for multiline messages

@startuml
actor Client as Client
participant "Foo service" as Foo
participant "Bar service" as Bar

Client -> Foo ++ : **GET /foo/:id/**
    Foo -> Foo : Do something\nwith data
    Foo -> Bar ++ : **GET /bar/:id/**
    Foo <-- Bar --
Client <-- Foo --
@enduml

Participants

@startuml
participant Participant as Foo
actor       Actor       as Foo1
boundary    Boundary    as Foo2
control     Control     as Foo3
entity      Entity      as Foo4
database    Database    as Foo5
collections Collections as Foo6
queue       Queue       as Foo7
Foo -> Foo1 : To actor
Foo -> Foo2 : To boundary
Foo -> Foo3 : To control
Foo -> Foo4 : To entity
Foo -> Foo5 : To database
Foo -> Foo6 : To collections
Foo -> Foo7: To queue
@enduml

Group participants

@startuml
actor Client as Client
box "Internal services" #LightBlue
    participant "Foo service" as Foo
    participant "Bar service" as Bar
end box

Client -> Foo ++ : **GET /foo/:id/**
    Foo -> Foo : Do something
    Foo -> Bar ++ : **GET /bar/:id/**
    Foo <-- Bar --
Client <-- Foo --
@enduml

Group part of the diagram

@startuml
actor Client as Client
participant "Foo service" as Foo
participant "Bar service" as Bar

Client -> Foo ++ : **GET /foo/:id/**
Foo -> Foo : Do something
Foo -> Bar ++ : **GET /bar/:id/**
Foo <-- Bar --
Client <-- Foo --

group "async flow"
    Bar -> Bar : Do something
end group
@enduml

Title, header, and footer

@startuml
title Example Title
header Page Header
footer Page %page% of %lastpage%

Alice -> Bob : message 1
Alice -> Bob : message 2
@enduml

Notes

@startuml
Alice->Bob : hello
note left: this is a first note

Bob->Alice : ok
note right: this is another note

Bob->Bob : I am thinking
note left
a note
can also be defined
on several lines
end note
@enduml

CLI

Make target to render diagrams

When adding documentation to a repo, I usually have the .plantuml files as siblings to the documentation file. I’ll then add the following to my Makefile. I then generate diagrams using make diagrams. The -checkmetadata flag will only render images where the source doesn’t match the previously-generated image.

diagrams:
    plantuml -metadata -checkmetadata -progress -tsvg ./docs/*.plantuml