widdershins下載 - widdershins原始碼下載

widdershins

其他源碼

v4.0.0

下載

威德辛斯

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' ) ;
} ) ;