UML : outils et PlantUML

Écrire les diagrammes en texte présente de nombreux avantages : ils se versionnent dans Git, se relisent en revue de code, se comparent (diff) et se régénèrent sans logiciel graphique. Deux outils dominent : PlantUML et Mermaid.

Choisir un outil

Outil	Avantages	Limites
PlantUML	Tous les diagrammes UML, très complet, rendu fidèle	Nécessite Java ; rendu hors navigateur
Mermaid	Rendu direct dans de nombreux outils (GitHub, GitLab, Gitea selon la version, éditeurs)	Moins de types de diagrammes, syntaxe plus limitée
draw.io, Excalidraw	Dessin libre, intuitif	Sources binaires ou XML difficiles à comparer
Éditeurs de base de données (DBeaver, pgModeler)	Schémas à partir d’une base existante	Niveau physique seulement

Installer PlantUML sur Ubuntu

sudo apt update
sudo apt install plantuml graphviz
plantuml -version

Le paquet installe aussi Java (dépendance). graphviz fournit le moteur de mise en page pour certains diagrammes (classes, composants). La version d’Ubuntu peut être en retard sur la dernière version de PlantUML ; pour la dernière, télécharger le fichier plantuml.jar depuis le site officiel et l’exécuter :

java -jar plantuml.jar -version

Générer une image

boutique.puml :

@startuml
class Client {
  - numClient: int
  - nom: String
  - email: String
}
class Commande {
  - numCommande: int
  - dateCommande: DateTime
  - statut: Statut
}
Client "1" -- "0..*" Commande : passe
@enduml

plantuml boutique.puml                  # produit boutique.png
plantuml -tsvg boutique.puml            # SVG (recommandé : net à toute taille)
plantuml -tsvg docs/diagrammes/*.puml   # plusieurs fichiers
plantuml -tsvg -o ../images docs/diagrammes/*.puml     # dossier de sortie
plantuml -checkonly boutique.puml       # vérifie la syntaxe sans produire d'image
plantuml -gui                           # interface graphique (si disponible)

Pour regénérer automatiquement à chaque modification :

sudo apt install inotify-tools
while inotifywait -e close_write boutique.puml; do plantuml -tsvg boutique.puml; done

Diagramme de classes

@startuml
skinparam classAttributeIconSize 0
hide empty members

enum Statut {
  nouvelle
  payee
  expediee
}

abstract class Personne {
  # nom: String
  # email: String
}

class Client extends Personne {
  - adresse: String
}

class Commande {
  - numCommande: int
  - statut: Statut
  + total(): Money
}

class LigneCommande {
  - quantite: int
  - prixUnitaire: Money
}

class Article {
  - reference: String
  - libelle: String
  - prix: Money
}

interface Notificateur {
  + envoyer(destinataire: String, message: String)
}

Client "1" -- "0..*" Commande : passe >
Commande "1" *-- "1..*" LigneCommande
LigneCommande "0..*" -- "1" Article
Commande --> Statut
class NotificateurSms implements Notificateur
@enduml

Syntaxe	Sens
`A "1" -- "0..*" B : verbe`	Association avec multiplicités
`A *-- B`	Composition
`A o-- B`	Agrégation
`A --> B`	Association orientée
`A ..> B`	Dépendance
`A <\|-- B` ou `B extends A`	Héritage
`A <\|.. B` ou `B implements A`	Réalisation d’une interface
`+ - # ~`	Visibilité
`enum`, `interface`, `abstract class`	Types particuliers

Voir Diagramme de classes.

Diagramme entité-association (base de données)

PlantUML sait aussi dessiner un modèle de base à la manière d’un schéma relationnel :

@startuml
hide circle
skinparam linetype ortho

entity "client" as client {
  * num_client : bigint <<PK>>
  --
  * nom : varchar(100)
  * email : varchar(255) <<UNIQUE>>
  adresse : text
}

entity "commande" as commande {
  * num_commande : bigint <<PK>>
  --
  * date_commande : timestamptz
  * statut : varchar(20)
  * num_client : bigint <<FK>>
}

entity "ligne_commande" as ligne {
  * num_commande : bigint <<PK, FK>>
  * reference : varchar(20) <<PK, FK>>
  --
  * quantite : integer
  * prix_unitaire : numeric(10,2)
}

entity "article" as article {
  * reference : varchar(20) <<PK>>
  --
  * libelle : varchar(200)
  * prix : numeric(10,2)
}

client ||--o{ commande
commande ||--|{ ligne
article ||--o{ ligne
@enduml

* marque une colonne obligatoire ; ||--o{ est la notation « pattes de corbeau » (un à plusieurs facultatif). C’est une vue du modèle physique (Du modèle physique au SQL).

Diagramme de cas d’utilisation et autres

@startuml
left to right direction
actor Client
actor Gestionnaire
rectangle "Boutique en ligne" {
  usecase "Passer une commande" as UC1
  usecase "S'authentifier" as UC2
  usecase "Gérer le stock" as UC3
}
Client --> UC1
UC1 .> UC2 : <<include>>
Gestionnaire --> UC3
@enduml

Les diagrammes de séquence, d’activité et d’états utilisent la même approche (exemples dans leurs pages).

Mermaid

Mermaid est interprété par le navigateur ; la syntaxe est plus compacte :

classDiagram
  class Client {
    -int numClient
    -String nom
    -String email
  }
  class Commande {
    -int numCommande
    -Statut statut
    +total() Money
  }
  Client "1" --> "0..*" Commande : passe

erDiagram
  CLIENT ||--o{ COMMANDE : passe
  COMMANDE ||--|{ LIGNE_COMMANDE : contient
  ARTICLE ||--o{ LIGNE_COMMANDE : figure
  CLIENT {
    bigint num_client PK
    varchar nom
    varchar email UK
  }

Pour produire des images en ligne de commande :

npm install -g @mermaid-js/mermaid-cli
mmdc -i diagramme.mmd -o diagramme.svg

Dans un fichier Markdown de dépôt, un bloc de code de langage mermaid est affiché par les plateformes qui le prennent en charge (selon leur version). Le site de cette documentation affiche les diagrammes sous forme d’images ou de blocs de texte : générer les images à la construction.

Intégrer à un projet

docs/
└── diagrammes/
    ├── boutique.puml            # sources (versionnées)
    ├── commande-sequence.puml
    └── images/
        ├── boutique.svg         # images générées
        └── commande-sequence.svg

package.json :

{
  "scripts": {
    "diagrammes": "plantuml -tsvg -o images docs/diagrammes/*.puml",
    "diagrammes:verifier": "plantuml -checkonly docs/diagrammes/*.puml"
  }
}

Pratique	Raison
Versionner les `.puml`	Historique et relecture
Générer les images en CI (ou les commiter)	Toujours à jour avec les sources
`plantuml -checkonly` dans l’intégration continue	Refuser une syntaxe invalide
Un fichier par diagramme, nommé par son sujet	Retrouver et réviser facilement
Diagramme près du code qu’il décrit	Mis à jour dans le même commit

Voir Gitea Actions : exemples pour une étape de génération en intégration continue (image de conteneur avec Java, ou paquet plantuml installé par apt).

Éditeurs

Éditeur	Extension
VS Code	« PlantUML » (rendu en direct, nécessite Java et Graphviz) ; « Mermaid Preview »
JetBrains	Greffon PlantUML
Neovim	`plantuml-previewer.vim`
Navigateur	Serveurs PlantUML publics en ligne : éviter d’y envoyer des schémas confidentiels (le texte part vers un serveur tiers)

Dessiner sans texte

Outil	Usage
draw.io (diagrams.net)	Schémas libres ; enregistrer en `.drawio` (XML) dans le dépôt, exporter en SVG
Excalidraw	Croquis rapides au style « dessiné à la main »
Looping, JMerise	Modèles Merise (Merise : méthode, outils et pièges)

Pour des esquisses, un tableau blanc reste le plus rapide : n’écrire un diagramme formel que pour ce qui doit être conservé.

Bonnes pratiques

Un diagramme par message, avec un titre.
Choisir un outil par projet.
Garder le texte lisible (alignement, noms explicites).
Utiliser skinparam avec modération (une feuille de style commune pour tout le projet).
Ne pas versionner uniquement l’image : toujours la source.
Relire le diagramme généré : la mise en page automatique peut surprendre.

Dépannage

Symptôme	Piste
`plantuml: command not found`	`sudo apt install plantuml`
`Cannot find Graphviz`	`sudo apt install graphviz`
`Syntax Error? (Assumed diagram type: …)`	Erreur de syntaxe à la ligne indiquée ; `plantuml -checkonly`
Image vide ou incomplète	Diagramme trop grand : `skinparam dpi`, ou `-tsvg`
Caractères accentués incorrects	`plantuml -charset UTF-8 fichier.puml`
Mise en page chaotique	Orienter (`left to right direction`), regrouper (`package`, `rectangle`), `skinparam linetype ortho`
Java absent	`sudo apt install default-jre-headless`
Mermaid ne s’affiche pas sur la plateforme	Version de la plateforme sans prise en charge : générer une image
Version de PlantUML trop ancienne (nouvelle syntaxe refusée)	Utiliser le fichier `plantuml.jar` récent

Ubuntu 24.04 et 26.04 : différences à connaître

Le paquet plantuml des dépôts Ubuntu a une version qui dépend de la version d’Ubuntu (voir apt policy plantuml) : une syntaxe récente peut être refusée avec une version plus ancienne. Java est installé automatiquement comme dépendance.

Pour aller plus loin

PlantUML, Mermaid, draw.io
Retour : Introduction à UML