Документация / PlantUML

Введение

PlantUML — язык, на котором диаграммы описываются текстом: участники, классы, состояния и связи задаются несколькими строками кода, а картинку строит программа. Такие диаграммы удобно хранить рядом с кодом, сравнивать версии и править вместе с командой.

@startuml
actor Клиент
participant "Интернет-магазин" as Shop
database "БД заказов" as DB

Клиент -> Shop : оформить заказ
Shop -> DB : сохранить заказ
DB --> Shop : id заказа
Shop --> Клиент : заказ №42 создан
@enduml

Как устроен редактор

Код — слева, диаграмма — справа; она перерисовывается по мере ввода, ошибки подсвечиваются в строке кода.
Холст масштабируется колесом мыши и перетаскивается; двойной щелчок по элементу переводит к его описанию в коде, при наведении подсвечиваются связи элемента.
Диаграммы оформлены в едином стиле сайта (светлая и тёмная тема). Собственные настройки оформления (skinparam, <style>, цвета элементов) применяются поверх темы — см. раздел «Оформление».
«Файл → Примеры» — готовые шаблоны основных типов диаграмм, «Файл → Скачать» — PUML, SVG и PNG.
Диаграммы сохраняются в аккаунте с историей версий, их можно добавить в проект и поделиться ссылкой.

Структура описания

Диаграмма описывается между строками @startuml и @enduml. Для некоторых типов используются свои директивы: @startmindmap, @startwbs, @startgantt, @startjson, @startyaml, @startsalt, @startregex, @startebnf, @startchen и другие — они указаны в соответствующих разделах.

Тип диаграммы определяется по содержимому: стрелки между участниками дают диаграмму последовательности, объявления class — диаграмму классов, start и действия в :…; — диаграмму активности и т. д. Смешивать элементы разных типов в одной диаграмме нельзя (кроме описательных диаграмм — компоненты, варианты использования и развёртывание можно сочетать).

Общие элементы

Заголовок, подписи и легенда

@startuml
title Оплата заказа
header Черновик
footer Страница %page% из %lastpage%
caption Рисунок 1. Основной сценарий

Клиент -> Банк : оплатить
Банк --> Клиент : успешно

legend right
  Сплошная стрелка — запрос
  Пунктирная — ответ
endlegend
@enduml

Заметки

Заметки есть почти во всех типах диаграмм: note left, note right, note top, note bottom (у элемента) или отдельные заметки с именем, связанные с элементами.

@startuml
class Заказ
note right of Заказ : создаётся из корзины
note "Общая заметка" as N1
Заказ .. N1
@enduml

Форматирование текста (Creole)

В подписях и заметках работает разметка: **жирный**, //курсив//, ""моноширинный"", --зачёркнутый--, __подчёркнутый__, списки (*, #), таблицы (|= Заголовок |), горизонтальные линии (----), переносы строк — \n.

@startuml
note as N
  **Важно:** //оплата// через ""/api/pay""
  * пункт списка
  * ещё пункт
  |= Код |= Значение |
  | 200 | успех |
  | 402 | нет денег |
end note
@enduml

Что поддерживается

Диаграмма	Директива	Раздел
Последовательности	`@startuml`	Диаграммы последовательности
Вариантов использования	`@startuml`	Варианты использования
Классов и объектов	`@startuml`	Классы; Объекты
Активности	`@startuml`	Диаграммы активности
Компонентов и развёртывания	`@startuml`	Компоненты и развёртывание
Состояний	`@startuml`	Диаграммы состояний
Временная	`@startuml`	Временные диаграммы
ER (информационная инженерия и нотация Чена)	`@startuml`, `@startchen`	ER-диаграммы
Интеллект-карта и WBS	`@startmindmap`, `@startwbs`	Интеллект-карты и WBS
Гант	`@startgantt`	Диаграмма Ганта
JSON и YAML	`@startjson`, `@startyaml`	Данные JSON и YAML
Каркасы интерфейсов (Salt)	`@startsalt`	Каркасы интерфейсов
C4, ArchiMate, сетевые диаграммы	`@startuml`, `@startnwdiag`	C4, ArchiMate и сети
Регулярные выражения, EBNF	`@startregex`, `@startebnf`	Прочие диаграммы

Ограничения

Подключаются только файлы стандартной библиотеки: !include <C4/C4_Container>. Локальные файлы и адреса в интернете (!include file.puml, !includeurl) недоступны — это ограничение безопасности сервера.
Не поддерживаются диаграммы ditaa, @startchronology и формулы (@startmath, @startlatex).
Очень большие диаграммы ограничены размером изображения и временем отрисовки — разбивайте их на части.

Документация основана на справочнике языка PlantUML (plantuml.com), адаптирована под возможности «Помощника SA». Нишевые возможности (например, диаграммы Ганта с ресурсами по часам или редкие параметры оформления) описаны кратко или опущены.