6.1. widdershins

这是一个可以将openapi文档转换成markdown的nodejs工具。

widdershins openapi.yaml -o openapi.md

6.1.1. 模板语法

Templates are compiled with doT.js.

小技巧

doT.js 是一个轻量级、高性能的 JavaScript 模板引擎库，用于在客户端或服务器端动态生成 HTML 或其他格式的文本内容。它以简洁、高效和灵活著称，尤其适合需要高性能模板渲染的场景。

特点

  • 轻量级：doT.js 是一个非常小的库（压缩后仅几 KB），加载快速，对性能影响微乎其微。

  • 高性能：它的模板渲染速度很快，适合高频率动态内容生成，性能在同类模板引擎中表现优异。

  • 灵活性：支持嵌套模板、条件语句、循环和任意 JavaScript 表达式，能够灵活地满足各种复杂需求。

  • 无依赖性：doT.js 是一个独立的库，不需要依赖其他框架或库。

  • 预编译支持：提供了预编译功能，可以在运行时直接使用编译好的模板函数，从而进一步提升性能。

使用场景

  • 客户端动态页面渲染。

  • Node.js 服务端模板渲染。

  • 需要高性能的批量数据渲染任务。

模板标记

  • {{= … }}：插入值。

  • {{ … }}：执行任意 JavaScript 代码。

  • {{! … }}：插入未经 HTML 转义的内容（类似 EJS 的 <%- %>）。

  • {{# … #}}：注释，内容不会出现在最终渲染的模板中。

默认情况下，Widdershins 使用其 templates/ 文件夹中的模板生成 Markdown 输出。要自定义模板，可以将部分或全部模板复制到一个文件夹中，并将该文件夹的位置传递给 user_templates 参数。

这些模板包括 .dot 模板和 .def 部分模板。要覆盖 .dot 模板，必须同时复制它引用的子 .def 部分模板。同样，要覆盖 .def 部分模板，也必须复制其父 .dot 模板。对于 OpenAPI 3，主要模板是 main.dot，其主要的子部分模板包括 parameters.def、responses.def 和 callbacks.def。

因此，通常最简单的方法是将所有 .dot 和 .def 文件复制到用户模板目录中，以免遗漏模板或部分模板。如果需要引入 Widdershins 更新中的更改，可以使用支持目录对比的可视化差异工具，例如 Meld 或 WinMerge。

要在模板中打印参数或变量的值，请使用代码 {{=parameterName}}。 例如，要打印 OpenAPI 3 规范的标题（来自其 info.title 字段）， 可以使用代码 {{=data.api.info.title}}。

要遍历数组中的值，可以使用代码 {{~ arrayName :tempVariable}} 开始循环，并使用代码 {{~}} 结束循环。 例如，OpenAPI 3 的 parameters.def 部分使用此代码来创建操作中参数的表：

|Name|In|Type|Required|Description|
|---|---|---|---|---|
{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{=p.safeType}}|{{=p.required}}|{{=p.shortDesc || 'none'}}|
{{~}}

对于 if/then 逻辑，可以使用代码 {{? booleanExpression}} 开始代码块，并使用代码 {{?}} 结束代码块。 例如，OpenAPI 3 的 main.dot 模板调用了 security.def 部分， 如果 OpenAPI 规范包含 securitySchemes 部分，则显示有关安全方案的信息：

{{? data.api.components && data.api.components.securitySchemes }}
{{#def.security}}
{{?}}

您可以通过在花括号内插入代码块，在模板中运行任意 JavaScript。例如，以下代码创建了一个变量，并在模板的后续部分使用普通的 doT.js 语法引用它：

{{ {
let message = "Hello!";
} }}

{{=message}}