SwiftPlantUML

使用此命令行界面 (CLI) 和 Swift 包从 Swift 代码生成 UML 类图。

使用一个或多个 Swift 文件作为图表的输入，以可视化 class、struct、protocol、enum 和 extension 类型，以及它们的实例和静态成员，以及它们的继承和实现关系。

目录 (点击展开)

SwiftPlantUML

用法

命令行

生成和渲染图表的示例，基于单个 Swift 文件，在您的浏览器中显示

swiftplantuml ./Tests/SwiftPlantUMLFrameworkTests/TestData/basics.txt

在包含要用于图表生成的 Swift 文件的目录中运行 swiftplantuml。将递归搜索目录。

$ swiftplantuml classdiagram --help
OVERVIEW: Generate PlantUML script and view it and diagram in browser

USAGE: swift-plant-uml classdiagram [--config <config>] [--exclude <exclude> ...] [--output <format>] [--sdk <sdk>] [--verbose] [<paths> ...]

ARGUMENTS:
  <paths>                 List of paths to the files or directories containing
                          swift sources

OPTIONS:
  --config <config>       Path to custom configuration filed (otherwise will
                          search for `.swiftplantuml.yml` in current directory)
  --exclude <exclude>     paths to ignore source files. Takes precedence over
                          arguments
  --output <format>       Defines output format. Options: browser,
                          browserImageOnly, consoleOnly
  --sdk <sdk>             MacOSX SDK path used to handle type inference
                          resolution, usually `$(xcrun --show-sdk-path -sdk
                          macosx)`
  --hide-extensions/--merge-extensions/--show-extensions
                          Decide if/how Swift extensions shall be considered for class diagram generation (default:
                          hideExtensions)
  --verbose               Verbose
  --version               Show the version.
  -h, --help              Show help information.

由于 classdiagram 是默认子命令，因此您可以省略它。

注意：使用类型推断声明的变量（例如 var hasBasket = false）在图表中显示为未知类型，除非您指定 sdk 参数

类型推断详情 (点击展开)

在以下示例中，属性 hasBasket 的类型为 Bool，但该类型是推断的，而不是显式声明的。

class Bicycle: Vehicle {
    var hasBasket = false
}

SwiftPlantUML 需要 macosx SDK 才能正确识别推断的类型。如果您安装了 Xcode（包括 macosx SDK），请使用 --sdk $(xcrun --show-sdk-path -sdk macosx)。

	没有推断类型（默认）	推断的类型
生成的 PlantUML	`~hasBasket`	`~hasBasket : Bool`
命令	`swiftplantuml classdiagram Tests/SwiftPlantUMLFrameworkTests/TestData/demo.txt`	`swiftplantuml classdiagram Tests/SwiftPlantUMLFrameworkTests/TestData/demo.txt --sdk $(xcrun --show-sdk-path -sdk macosx)`

Swift 包

dependencies: [
    .package(url: "https://github.com/MarcoEidinger/SwiftPlantUML.git", .upToNextMajor(from: "0.5.0"))
]

本项目尚未达到主要版本。随时可能会发生任何变化，公共 API 不应被视为稳定。但是，我将尝试为新的次要版本保留重大更改。您可能会更倾向于将版本固定到 .upToNextMinor 甚至 .exact 版本。

API 文档

Xcode 源代码编辑器扩展

有关更多详细信息，请参阅 MarcoEidinger/SwiftPlantUML-Xcode-Extension

安装

使用 Homebrew

brew install swiftplantuml

以前，您可以使用 brew install MarcoEidinger/formulae/swiftplantuml（您仍然可以）

使用 Mint

$ mint install MarcoEidinger/SwiftPlantUML

从源代码安装

您还可以通过克隆此项目并运行 make install（Xcode 12 或更高版本）从源代码构建和安装。

手动运行以下命令以手动构建和安装

$ git clone https://github.com/MarcoEidinger/SwiftPlantUML.git
$ cd SwiftPlantUML
$ make install

注意：处理多个 Swift 版本

SwiftPlantUML 挂钩到 SourceKit，因此需要 Swift 工具链。

您应该始终使用与编译代码相同的工具链运行 SwiftPlantUML。

如果您安装了多个工具链或 Xcode，您可能需要覆盖 SwiftPlantUML 的默认 Swift 工具链。

以下是 SwiftPlantUML 确定使用哪个 Swift 工具链的顺序

$XCODE_DEFAULT_TOOLCHAIN_OVERRIDE
$TOOLCHAIN_DIR 或 $TOOLCHAINS
xcrun -find swift
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
~/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
~/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain

预计在上述路径中的 usr/lib/ 子目录中找到 sourcekitd.framework。

因此，如果您遇到Fatal error: Loading sourcekitd.framework/Versions/A/sourcekitd failed，请检查 xcode-select -p 的结果，以查看该目录随后是否包含 Swift 工具链。您可以使用 sudo xcode-select -s <pathToYourXcodeInstallation> 来纠正这种情况，例如

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

配置

通过从您将运行 SwiftPlantUML 的目录中添加 .swiftplantuml.yml 文件来配置 SwiftPlantUML。注意：可以使用 Configuration 以编程方式设置相同的配置选项。

选项

您可以

包含/排除文件（支持通配符）
按名称包含/排除元素（支持通配符）
根据元素的访问级别限制元素和成员，例如，仅显示 public 类型
隐藏扩展或合并扩展（与其已知的类型）

显示扩展（默认）	合并扩展	隐藏扩展

杂乱但准确地表示代码库	减少杂乱。没有信息丢失	没有杂乱但信息丢失

隐藏嵌套类型
隐藏成员访问级别属性
配置样式，使用 skin parameters 甚至包含外部文件或 themes
基于父级排除继承关系（支持通配符），例如，不显示对 Codable 的继承

主题

默认	Amiga	Reddress-darkblue	Sketchy Outline	还有更多可用
				有关更多示例，请参见 here

示例

简单示例

files:
    exclude:
    - "Tests/**/*.swift" # paths to ignore for diagram. Takes precedence over `included`.
elements:
  havingAccessLevel:
  - public
  - open
  showMembersWithAccessLevel:
  - public
  - open
  showNestedTypes: false
  showExtensions: merged
theme: plain # see https://plantuml.com/theme
texts:
  title: |
    <u>Formatted</u> title example
    on <i>several</i> lines and using <font color=red>html</font>
skinparamCommands: # see https://plantuml.com/skinparam
- skinparam classBackgroundColor PaleGreen
- skinparam classArrowColor SeaGreen
- skinparam classBorderColor SpringGreen
- skinparam stereotypeCBackgroundColor YellowGreen
- skinparam stereotypeCBackgroundColor<< Foo >> DimGray
relationships:
  inheritance:
    label: "inherits from"
    style:
      lineStyle: dotted
      lineColor: DarkViolet
      textColor: DarkViolet
    exclude:
    - "Codable"

丰富的示例：here

编辑期间的代码补全

要在编辑期间获得代码补全，请使用 Visual Studio Code，Red Hat 创建的 YAML 扩展和 SwiftPlantUML 的 JSON 模式。

在 Visual Studio Code 中：Code -> Preferences -> Settings -> 搜索 yaml

点击 Edit in settings.json 并添加相应的条目

"yaml.schemas": {"https://raw.githubusercontent.com/MarcoEidinger/SwiftPlantUML/main/Configuration/Schema/json-schema-swiftplantuml.json": "/.swiftplantuml.yml" }

大型图表

像 PlantText 这样的在线工具不支持大型图表。如果 PlantText 在浏览器中未完全呈现您的图表图像（或根本不可见），则

下载 PlantUML Java 归档文件到您的机器
使用 swiftplantuml 生成脚本并
在本地使用 plantuml 生成实际图像

这是相应的命令（假设 plantuml.jar 是从 swifptlantuml 运行的当前目录下载的）

swiftplantuml ./Sources/ --output consoleOnly > sources.txt | java -DPLANTUML_LIMIT_SIZE=8192 -jar plantuml.jar $1

这将导致创建 sources.png 文件，其中包含高达大小限制的类图。

PlantUML 将图像的宽度和高度限制为 4096，并可以选择覆盖此限制 (-DPLANTUML_LIMIT_SIZE)，我在上面的命令中使用了该选项。

在下表中，您可以看到基于相同脚本的类图输出的差异。仅供参考：此脚本/图表有 63 个实体。

PlantText 输出	PlantUML 输出（默认大小限制）	PlantUML 输出（自定义大小限制）

从二进制框架生成 UML 文档

您可以使用 swifplantuml 解析二进制框架的 .swiftmodule 文件，有关详细信息和具体示例，请阅读我的文章从二进制框架 (xcframework) 生成 UML 文档。

计划的改进

能够呈现元素之间的关联

已知限制

请参阅大型图表

日志

默认情况下，CLI 将仅记录错误消息。

要记录具有较低优先级的消息（警告、信息、调试），请使用 --verbose 选项。

注意：使用 --output consoleOnly 在控制台中打印 PlantUML 脚本会将任何消息记录到日志文件中。这样做的好处是您可以毫无问题地将 PlantUML 脚本管道传输到文件中。您可以使用 tail -f /tmp/swiftplantuml.log 来跟踪日志文件

帮助手册

使用 Homebrew 或从源代码 (make install) 安装 swiftplantuml 也会安装一个帮助手册，您可以使用以下命令查看该手册

man swiftplantuml

鸣谢

该项目受到了 https://github.com/palaniraja/swiftuml 及其各种前身的影响。出于个人偏好，我选择启动一个新项目。我想为 Swift 开发者提供一个用 Swift 编写的工具！这有望使我和潜在的贡献者能够更快更有效地进行计划中的改进。

最后但并非最不重要的一点是，非常感谢 PlantUML 的伟大开发者以及运营相关在线服务器/工具的人员，这些服务器/工具可在 http://plantuml.com/ 和 https://www.planttext.com/ 上获得。