widdershins

威德辛斯

OpenAPI / Swagger / AsyncAPI / Semoasa 定义到 Slate / ReSlate 兼容的 markdown

Widdershins副词:

• 与太阳运行方向相反的方向；
• 逆时针；
• 帮助您根据 OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0 定义生成静态文档

消息

• 4.0版本变化：
  • 现在使用 Promise 而不是回调
  • 直接输出 html 和 ReSpec 格式的选项
  • 统一的 JavaScript 和 Node.js 代码示例，添加了 PHP
  • 添加到架构模板的restrictions列（ readOnly / writeOnly ）
  • 许多错误修复
• 从 v3.0.0 开始，Widdershins 默认不再扩展 OpenAPI 主体参数/requestBodies 的定义，除非它们具有内联模式。您可以使用--expandBody选项恢复旧的行为。
• 您可以使用--maxDepth选项限制模式示例的深度。默认值为 10。
• 要完全省略架构，请复制并自定义main.dot模板。
• 从 v3.1.0 开始，Widdershins 在 OpenAPI 代码示例中包含生成的Authorization标头。如果您想省略此内容，请参阅此处。

安装

• 克隆 git 存储库，然后npm i安装依赖项，或者
• npm install -g widdershins全局安装

入门

Widdershins 通常用作 API 文档管道中的一个阶段。该管道以 OpenAPI 3.x、OpenAPI 2.0 (fka Swagger)、API Blueprint、AsyncAPI 或 Semoasa 格式的 API 定义开始。 Widdershins 将此描述转换为适合渲染器使用的 markdown，例如 Slate、ReSlate、Shins（已弃用）或适合与 ReSpec 一起使用的 html。

如果您需要创建输入 API 定义，此可用编辑器列表可能会很有用。

此处提供了更深入的文档。

示例

 node widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --summary defs/petstore3.json -o petstore3.md

选项

CLI 参数名称	JavaScript 参数名称	类型	默认值	描述
--剪贴板	选项.剪贴板	boolean	true	设置标题中code_clipboard属性的值，以便 Markdown 处理器可以包含剪贴板支持。
--customApiKeyValue	选项.customApiKeyValue	string	ApiKey	设置自定义 API 密钥值以用作生成的代码示例中的 API 密钥。
--展开主体	选项.expandBody	boolean	false	如果方法的 requestBody 参数通过引用引用架构（不使用内联架构），则默认情况下，Widdershins 仅显示对此参数的引用。将此选项设置为 true 以展开架构并显示请求正文中的所有属性。
--标题	选项.标题	integer	2	在标题中设置headingLevel参数的值，以便 Markdown 处理器知道在目录中显示多少个标题级别。目前只有 Shins 支持，Slate 不支持，Slate 缺乏此功能。
--省略主体	选项.omitBody	boolean	false	默认情况下，Widdershins 将正文参数作为参数表中的一行包含在表示正文中字段的行之前。设置此参数以省略该主体参数行。
--省略标题	选项.omitHeader	boolean	false	在生成的 Markdown 文件中省略标头/YAML front-matter。
- 解决	选项.解决	boolean	false	使用source参数或输入文件作为基本位置来解析外部 $refs。
--浅模式	选项.shallowSchemas	boolean	false	当使用 $ref 引用架构时，不要显示该架构的完整内容。
不适用	选项.源	string	没有任何	用作解析相对引用 ($refs) 的基础的源文件的绝对位置或 URL；如果 options.resolve 设置为 true，则为必需。对于 CLI 命令，Widdershins 使用输入文件作为 $refs 的基础。
- 概括	options.toc摘要	boolean	false	使用操作摘要作为 TOC 条目而不是 ID。
--useBodyName	选项.useBodyName	boolean	使用 OpenAPI 2.0 主体参数的原始参数名称。
-v, --详细	选项.详细	boolean	false	增加冗长程度。
-h，--帮助	选项.帮助	boolean	false	显示帮助。
- 版本	选项.版本	boolean	false	显示版本号。
-c，--代码	选项.codeSamples	boolean	false	省略生成的代码示例。
--httpsnippet	选项.httpsnippet	boolean	false	使用 httpsnippet 生成代码示例。
-d, --发现	选项.发现	boolean	false	包括 schema.org WebAPI 发现数据。
-e，--环境	不适用	string	没有任何	从中加载配置选项的文件。
-i, --包括	选项.includes	string	没有任何	要放入输出 Markdown 的include头中的文件列表。然后，诸如 Shins 之类的处理器可以导入这些文件的内容。
-l, --lang	选项.lang	boolean	false	根据源文件的x-code-samples示例中使用的语言生成代码示例的语言列表。
--语言选项卡	选项.语言_选项卡	string	（每种输入类型有所不同）	使用 language[:label[:client]] 格式的代码示例的语言选项卡列表，例如javascript:JavaScript:request 。
-m, --最大深度	选项.maxDepth	integer	10	显示模式示例的最大深度。
-o, --outfile	不适用	string	没有任何	将输出 Markdown 写入的文件。如果留空，Widdershins 会将输出发送到 stdout。
-r，--原始	options.sample 的逆	boolean	false	输出原始模式而不是示例值。
-s，--搜索	选项.搜索	boolean	true	在标头中设置search参数的值，以便 Slate 等 Markdown 处理器在其输出中包含或不包含搜索。
-t, --主题	选项.主题	string	达库拉	要使用的语法荧光笔主题。
-u, --user_templates	选项.user_templates	string	没有任何	从中加载覆盖模板的目录。
-x, --实验性的	选项.实验	boolean		将 httpSnippet 用于多部分媒体类型。
-y，--yaml	选项.yaml	boolean	false	以 YAML 格式显示 JSON 架构。
	options.templateCallback	function	没有任何	在每个模板之前和之后调用的function （仅限 JavaScript 代码）。
	选项.toc_footers	object	要添加到 ToC 页脚数组的url和description映射（仅限 JavaScript 代码）。

在 Node.JS 代码中，创建一个选项对象并将其传递给 Widdershins convert函数，如下例所示：

 const converter = require ( 'widdershins' ) ;
let options = { } ; // defaults shown
options . codeSamples = true ;
options . httpsnippet = false ;
//options.language_tabs = [];
//options.language_clients = [];
//options.loadedFrom = sourceUrl; // only needed if input document is relative
//options.user_templates = './user_templates';
options . templateCallback = function ( templateName , stage , data ) { return data } ;
options . theme = 'darkula' ;
options . search = true ;
options . sample = true ; // set false by --raw
options . discovery = false ;
options . includes = [ ] ;
options . shallowSchemas = false ;
options . tocSummary = false ;
options . headings = 2 ;
options . yaml = false ;
//options.resolve = false;
//options.source = sourceUrl; // if resolve is true, must be set to full path or URL of the input document
converter . convert ( apiObj , options )
. then ( str => {
  // str contains the converted markdown
} )
. catch ( err => {
  console . error ( err ) ;
} ) ;

要仅包含预定义语言选项卡的子集，或重命名其显示名称，您可以覆盖options.language_tabs ：

 options . language_tabs = [ { 'go' : 'Go' } , { 'http' : 'HTTP' } , { 'javascript' : 'JavaScript' } , { 'javascript--node' : 'Node.JS' } , { 'python' : 'Python' } , { 'ruby' : 'Ruby' } ] ;

--environment选项指定 JSON 或 YAML 格式的options对象，例如：

{
  "language_tabs" : [{ "go" : " Go " }, { "http" : " HTTP " }, { "javascript" : " JavaScript " }, { "javascript--node" : " Node.JS " }, { "python" : " Python " }, { "ruby" : " Ruby " }],
  "verbose" : true ,
  "tagGroups" : [
    {
      "title" : " Companies " ,
      "tags" : [ " companies " ]
    },
    {
      "title" : " Billing " ,
      "tags" : [ " invoice-create " , " invoice-close " , " invoice-delete " ]
    }
  ]
}

您还可以使用环境文件将 OAS/Swagger 标记路径分组在一起，以创建更优雅的目录和整体页面结构。

如果您需要支持 Slate <v1.5.0 的版本（或渲染器也不支持语言选项卡的显示名称，例如node-slate 、 slate-node或whiteboard ），您可以使用--environment使用包含的whiteboard_env.json文件的--environment选项即可轻松实现此目的。

如果您使用httpsnippet选项生成代码示例，则可以通过覆盖options.language_clients来指定用于执行每种语言的请求的客户端库：

 options . language_clients = [ { 'shell' : 'curl' } , { 'node' : 'request' } , { 'java' : 'unirest' } ] ;

如果语法高亮所需的 markdown 名称与 httpsnippet 所需目标之间的语言名称不同，则两者都可以以markdown--target形式指定。

要查看 httpsnippet 支持的语言和客户端列表，请单击此处。

仅当 OpenAPI / Swagger 定义未指定主机，并且（根据 OpenAPI 规范）API 端点被视为基于加载定义的源 URL 时，才需要loadedFrom选项。

要查看highlight-js 语法突出显示主题的列表，请单击此处。

如果上面的discovery选项设置为true则包含 Schema.org WebAPI 发现数据。有关详细信息，请参阅 W3C WebAPI 发现社区组。

语言选项卡

Widdershins 支持x-code-samples供应商扩展来完全自定义您的文档。或者，您可以编辑templates子目录中的默认代码示例，或使用user_templates选项覆盖它们以指定包含模板的目录。

Widdershins 支持使用相同语言的多语言选项卡（即纯 Javascript 和 Node.Js）。要使用此支持，您必须使用 Slate（或其兼容的端口之一）版本 1.5.0 或更高版本。

模板

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

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

这意味着通常最简单的方法是将所有.dot和.def文件复制到用户模板目录中，这样您就不会跳过模板或部分模板。要引入 Widdershins 更新中的更改，您可以使用可以跨两个目录运行的可视化diff工具，例如 Meld 或 WinMerge。

模板语法

模板是用 doT.js 编译的。

模板可以访问具有基于文档上下文的一系列属性的data对象。有关参数的信息，请参阅相应模板的自述文件：

• Swagger 2.0 / OpenAPI 3.0.x 模板参数
• AsyncAPI 1.x 模板参数
• Semoasa 0.1.0 模板参数

要打印模板中参数或变量的值，请使用代码{{=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 规范包含securitySchemes部分，则 OpenAPI 3 main.dot模板会调用security.def部分来显示有关安全方案的信息：

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

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

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

{{=message}}

模板回调

templateCallback参数指向 Widdershins 在每个模板运行之前和之后调用的函数。回调函数接收一个data对象，其中包含 Widdershins 正在处理的规范；该函数必须返回该对象。仅当您从 JavaScript 代码而不是命令行调用 Widdershins 时，才可以使用回调函数。

Widdershins 将这些变量传递给回调函数：

• templateName ：模板的名称，例如main 。
• stage ：Widdershins 是在模板之前 ( pre ) 还是之后 ( post ) 调用回调函数。
• data ：包含 Widdershins 正在处理的数据的对象。您可以以任何您认为合适的方式改变data对象，但无论函数是否更改它都必须返回它。您放入data.append属性中的内容将附加到当前输出流。

例如，以下 JavaScript 代码在输出 Markdown 中打印模板的名称和处理阶段：

 'use strict' ;

const converter = require ( 'widdershins' ) ;
const fs = require ( 'fs' ) ;

let options = { } ;
options . templateCallback = myCallBackFunction ;

function myCallBackFunction ( templateName , stage , data ) {
  let statusString = "Template name: " + templateName + "n" ;
  statusString += "Stage: " + stage + "n" ;
  data . append = statusString ;
  return data ;
}

const apiObj = JSON . parse ( fs . readFileSync ( 'defs/petstore3.json' ) ) ;

converter . convert ( apiObj , options )
. then ( str => {
  fs . writeFileSync ( 'petstore3Output.md' , str , 'utf8' ) ;
} ) ; 

测试

运行测试套件：

 node testRunner {path-to-APIs}

测试工具当前需要.yaml或.json文件，并且已经过测试

• API大师
• Mermade OpenAPI 定义集合

此工具与其他 OpenAPI / Swagger to Slate 工具之间的比较

Widdershins 作者的博客文章。

致谢

• @latgeek 的标志。
• @vfernandestoptal 支持 httpsnippet。

野外的威德辛

请随时在此处添加指向您的 API 文档的链接。

• GOV.UK 内容 API v1.0.0
• GOV 英国数字市场 API v1.0.0
• 第一资本 A​​PI
• 认知数据API
• SpeckleWorks API
• 通过API银行
• 开放EO API
• 拆分付款 API
• LeApp 守护进程 API
• Shutterstock API
• Shotstack 视频编辑 API
• Admetricks API
• Eqivo API

Widdershins 和 ReSlate

• Widdershins与 Slate 配合得很好，但如果想要获得完全基于 Node.js 的体验，为什么不尝试 ReSlate 端口呢？