本体文档生成器 SimpleOntoDoc

本体静态文档生成器：实现与应用

SimpleOntoDoc 是一款用于创建静态网站以记录本体的工具。本体通过类、属性及其之间的关系来描述一个主题领域。该项目主要面向企业内部模型和标准（如 CIM/IEC61970），但也具有更广泛的应用场景。

该工具生成导航、图表、属性表和搜索功能。它支持解析 JSON 模式描述，使用 PlantUML 渲染 UML 图表，并采用 Bootstrap 构建界面。

生成网站的结构

首页提供快速访问的磁贴：类、枚举、基本类型、数据类型、复合类型。每个磁贴按类型筛选实体。页头包含不区分大小写的名称和描述搜索功能。

实体标签页显示所有实体的表格，支持交互式搜索。行可点击，跳转至类页面。

在类页面（例如：PowerSystemResource）上：

• 描述和继承层次结构 + 外向关系的 UML 图表。
• 属性表，包含可点击的 ID。
• 摘要块：导航到父类、子类以及作为数据类型的用法。
• 引用表：其他类中以此类为类型的属性。
• 子类表。

图表具有交互性：支持平移缩放导航，节点可点击。

属性页面（例如：PowerSystemResource.Controls）包括描述、摘要和导航。

项目中的应用

该工具适用于具有类似 UML 结构的领域：类、继承、组合。在 JSON 中描述本体（使用 model.py API），然后生成网站。

使用案例：

• 记录服务中的业务实体（50 多个类）。
• 开发人员、分析师和需求作者之间的通用语言。
• CI/CD：当 Git 中的 JSON 发生变化时生成网站。
• 代码生成或导出的基础。

在需求中将本体与业务逻辑分离。

技术栈

• C# / .NET 9：应用基础。
• PlantUML：通过临时服务器渲染 UML 图表。
• RazorLight：页面模板。
• Bootstrap 5：前端布局。

发布脚本构建包含 Nginx 的 Docker 容器。

与替代方案的比较

| 工具 | 优点 | 缺点 |

|------------|-------|--------|

| ontology.tno.nl | 为 CIM 提供现成网站 | 无源代码，未适配 GOST |

| Widoco | 支持 OWL | 单页面，信息冗余，设计问题 |

| Ontospy | 继承树 | 需修改以支持 JSON/UML |

SimpleOntoDoc 专注于描述的简洁性，接近编程语言，避免 RDF/OWL 的复杂性。

增强可能性

• 多语言界面。
• 带继承的类树视图。
• RDF/XML、OWL、XMI、PDF（GOST）的解析器。
• 验证：属性的最小值/最大值、正则表达式。
• 类/属性的元数据。
• 页面部分的锚点（#）。

关键要点

• 生成功能齐全的网站，具备搜索、图表和超链接。
• 输入：来自 model.py 的 JSON，输出：Docker 中的静态文件。
• 适配 CIM/GOST，可扩展。
• 面向中高级开发人员：专注于领域模型，无需 RDF 复杂性。
• CI 集成，实现实时文档。

— Editorial Team