OpenAPI в диаграмму классов PlantUML

Модель данных API проще обсуждать по диаграмме, чем по YAML. Диаграмму классов можно получить из спецификации автоматически и вставить в документацию или постановку.

Как получить диаграмму

1. Откройте спецификацию в редакторе OpenAPI.
2. Выберите Файл → Преобразовать в → PlantUML — диаграмма классов.
3. Откройте результат в песочнице PlantUML или сохраните в проект — диаграмма отрисуется справа.

Что попадает на диаграмму

• Каждая схема из components/schemas (или definitions в Swagger 2.0) — класс с полями и типами.
• Обязательные поля отмечены «+», необязательные — «~» и кратностью [0..1]; массивы — [*].
• Ссылка на другую схему — связь с кратностью (1, 0..1, *) и именем поля.
• allOf со ссылкой — наследование; oneOf/anyOf — абстрактный класс и реализации.
• Схемы с enum — перечисления.
• Вложенные объекты без отдельной схемы — отдельные классы, связанные композицией.
• Схемы из других файлов проекта по $ref тоже попадают на диаграмму.

Доработка

Результат — обычный код PlantUML, его можно править: убрать служебные схемы, сгруппировать классы в пакеты (package), изменить направление (left to right direction). Подробнее о синтаксисе — в гайде «Диаграмма классов в PlantUML». Скачать картинку — Файл → Скачать в PNG или SVG.

Пример результата

@startuml
title API библиотеки
hide empty methods
hide circle

class "Book" as Book {
  +id : string <uuid>
  +title : string
  ~author : Author [0..1]
  ~tags : string[*]
}

class "Author" as Author {
  +name : string
}

Book --> "0..1" Author : author
@enduml

Вопросы и ответы

Можно ли получить диаграмму последовательности по методам API? Нет: спецификация описывает отдельные операции, но не порядок их вызова. Последовательность рисуют вручную — см. «Диаграмма последовательности в PlantUML».

Диаграмма слишком большая — что делать? Удалите из кода PlantUML служебные схемы (ошибки, пагинацию) или разбейте диаграмму по пакетам — это обычный текст.