widdershins
v4.0.0
OpenAPI / Swagger / AsyncAPI / Semoasa 定義から Slate / ReSlate 互換のマークダウンへ
restrictions列 ( readOnly / writeOnly ) がスキーマ テンプレートに追加されました--expandBodyオプションを使用すると、以前の動作を復元できます。--maxDepthオプションを使用して、スキーマ例の深さを制限できます。デフォルトは 10 です。main.dotテンプレートをコピーしてカスタマイズしてください。Authorizationヘッダーが含まれています。省略したい場合はこちらをご覧ください。npm i依存関係をインストールするか、npm install -g widdershinsグローバルにインストールするWiddershins は通常、API ドキュメント パイプラインのステージとして使用されます。パイプラインは、OpenAPI 3.x、OpenAPI 2.0 (別名 Swagger)、API ブループリント、AsyncAPI、または Semoasa 形式の API 定義から始まります。 Widdershins は、この記述を、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プロパティの値を設定して、マークダウン プロセッサにクリップボード サポートを含めることができるようにします。 |
| --customApiKeyValue | options.customApiKeyValue | string | ApiKey | 生成されたコード例で API キーとして使用するカスタム API キー値を設定します。 |
| --expandBody | options.expandBody | boolean | false | メソッドの requestBody パラメータが (インライン スキーマではなく) 参照によってスキーマを参照している場合、デフォルトでは、Widdershins はこのパラメータへの参照のみを表示します。スキーマを展開し、リクエスト本文のすべてのプロパティを表示するには、このオプションを true に設定します。 |
| --見出し | オプション.見出し | integer | 2 | ヘッダーのheadingLevelパラメーターの値を設定して、マークダウン プロセッサが目次に表示する見出しレベルの数を認識できるようにします。現在、Shins のみでサポートされており、この機能がない Slate ではサポートされていません。 |
| --省略本文 | options.省略本文 | boolean | false | デフォルトでは、Widdershins は、パラメーター テーブル内の本文のフィールドを表す行の前に、本文パラメーターを行として含めます。このパラメータを設定して、本体パラメータ行を省略します。 |
| --省略ヘッダー | options.省略ヘッダー | boolean | false | 生成された Markdown ファイルのヘッダー/YAML 前部分を省略します。 |
| - 解決する | オプション.解決 | boolean | false | sourceパラメーターまたは入力ファイルをベースの場所として使用して、外部 $ref を解決します。 |
| --shallowスキーマ | options.shallowSchemas | boolean | false | $ref を使用してスキーマを参照する場合、スキーマの完全な内容を表示しないでください。 |
| 該当なし | オプション.ソース | string | なし | 相対参照 ($refs) を解決するためのベースとして使用するソース ファイルの絶対位置または URL。 options.resolve が true に設定されている場合は必須です。 CLI コマンドの場合、Widdershins は入力ファイルを $refs のベースとして使用します。 |
| - まとめ | options.toc概要 | boolean | false | ID の代わりに操作概要を TOC エントリとして使用します。 |
| --useBodyName | options.useBodyName | boolean | OpenAPI 2.0 本体パラメータには元のパラメータ名を使用します。 | |
| -v、--verbose | オプション.詳細 | boolean | false | 冗長性を高めます。 |
| -h、--ヘルプ | オプション.ヘルプ | boolean | false | ヘルプを表示します。 |
| --バージョン | オプション.バージョン | boolean | false | バージョン番号を表示します。 |
| -c、--code | options.codeSamples | boolean | false | 生成されたコードサンプルを省略します。 |
| --httpスニペット | options.httpスニペット | boolean | false | httpsnippet を使用してコード サンプルを生成します。 |
| -d、--ディスカバリー | オプション.ディスカバリー | boolean | false | schema.org WebAPI 検出データを含めます。 |
| -e、--環境 | 該当なし | string | なし | 構成オプションをロードするファイル。 |
| -i、--含む | オプションが含まれます | string | なし | 出力マークダウンのincludeヘッダーに入れるファイルのリスト。 Shins などのプロセッサは、これらのファイルの内容をインポートできます。 |
| -l、--lang | options.lang | boolean | false | ソース ファイルのx-code-samples例で使用されている言語に基づいて、コード サンプルの言語のリストを生成します。 |
| --言語タブ | オプション.言語タブ | string | (入力種類ごとに異なります) | language[:label[:client]] 形式 ( javascript:JavaScript:requestなど) を使用したコード サンプルの言語タブのリスト。 |
| -m、--maxDepth | options.maxDepth | integer | 10 | スキーマの例に表示する最大の深さ。 |
| -o、--outfile | 該当なし | string | なし | 出力マークダウンを書き込むファイル。空白のままにすると、Widdershins は出力を stdout に送信します。 |
| -r、--raw | options.samp の逆 | boolean | false | サンプル値の代わりに生のスキーマを出力します。 |
| -s、--検索 | オプション.検索 | boolean | true | Slate などの Markdown プロセッサが出力に検索を含めるかどうかを指定するには、ヘッダーにsearchパラメーターの値を設定します。 |
| -t、--テーマ | オプション.テーマ | string | ダークラ | 使用する構文ハイライターのテーマ。 |
| -u、--user_templates | オプション.user_templates | string | なし | オーバーライド テンプレートをロードするディレクトリ。 |
| -x、--実験的 | オプション.実験的 | boolean | マルチパート メディアタイプには httpSnippet を使用します。 | |
| -y、--yaml | オプション.yaml | boolean | false | JSON スキーマを YAML 形式で表示します。 |
| options.templateCallback | function | なし | 各テンプレートの前後で呼び出されるfunction (JavaScript コードのみ)。 | |
| options.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 . 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 . language_clients をオーバーライドすることで、各言語のリクエストを実行するために使用されるクライアント ライブラリを指定できます。
options . language_clients = [ { 'shell' : 'curl' } , { 'node' : 'request' } , { 'java' : 'unirest' } ] ;構文ハイライトに必要なマークダウン名と httpsnippet に必要なターゲットの間で言語名が異なる場合は、両方をmarkdown--target形式で指定できます。
httpsnippet でサポートされている言語とクライアントのリストを表示するには、ここをクリックしてください。
loadedFromオプションは、OpenAPI / Swagger 定義でホストが指定されておらず、(OpenAPI 仕様に従って) API エンドポイントが定義のロード元のソース URL に基づいていると見なされる場合にのみ必要です。
Highlight-js 構文強調表示テーマのリストを表示するには、ここをクリックしてください。
上記のdiscoveryオプションがtrue設定されている場合、Schema.org WebAPI 検出データが含まれます。詳細については、「W3C WebAPI Discovery Community Group」を参照してください。
Widdershins は、ドキュメントを完全にカスタマイズするためのx-code-samplesベンダー拡張機能をサポートしています。あるいは、 templatesサブディレクトリ内のデフォルトのコードサンプルを編集するか、 user_templatesオプションを使用してテンプレートを含むディレクトリを指定してコードサンプルをオーバーライドすることもできます。
Widdershins は、同じ言語 (つまり、プレーンな Javascript と Node.Js) での複数の言語タブの使用をサポートしています。このサポートを使用するには、スレート (またはそれと互換性のあるそのポートの 1 つ) バージョン 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 アップデートからの変更を取り込むには、Meld や WinMerge など、2 つのディレクトリ間で実行できる視覚的なdiffツールを使用できます。
テンプレートは doT.js でコンパイルされます。
テンプレートは、ドキュメントのコンテキストに基づいたさまざまなプロパティを持つdataオブジェクトにアクセスできます。パラメータの詳細については、適切なテンプレートの README ファイルを参照してください。
テンプレート内のパラメータまたは変数の値を出力するには、コード{{=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 が呼び出す関数を指します。コールバック関数は、Widdershins が処理している仕様を含むdataオブジェクトを受け取ります。関数はこのオブジェクトを返す必要があります。コールバック関数は、コマンド ラインからではなく、JavaScript コードから Widdershins を呼び出す場合にのみ使用できます。
Widdershins はこれらの変数をコールバック関数に渡します。
templateName : テンプレートの名前mainなど)。stage : Widdershins がテンプレートの前 ( pre ) または後 ( post ) にコールバック関数を呼び出すかどうか。data : Widdershins が処理しているデータを含むオブジェクト。 dataオブジェクトは、適切と思われる方法で変更できますが、変更するかどうかに関係なく、関数はそれを返す必要があります。 data.appendプロパティに入力したコンテンツは、現在の出力ストリームに追加されます。たとえば、次の JavaScript コードは、テンプレートの名前と処理ステージを出力マークダウンに出力します。
'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ファイルを想定しており、テストされています。
Widdershins の著者によるブログ投稿。
API ドキュメントへのリンクをここに自由に追加してください。
Widdershins Slate とうまく連携しますが、Node.js ベースのみのエクスペリエンスを求める場合は、ReSlate ポートを試してみてはいかがでしょうか。
