widdershins
=================================

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

.. code-block:: bash

    widdershins openapi.yaml -o openapi.md


模板语法
------------------------------------

Templates are compiled with `doT.js <https://github.com/olado/doT#readme>`_.

.. tip:: 

    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 部分使用此代码来创建操作中参数的表：

.. code-block:: text

    |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 部分，则显示有关安全方案的信息：

.. code-block:: text

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

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

.. code-block:: text

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

    {{=message}}