widdershins
v4.0.0
OpenAPI/Swagger/AsyncAPI/Semoasa-Definition für Slate/ReSlate-kompatibles Markdown
restrictions ( readOnly / writeOnly ) zu Schemavorlagen hinzugefügt--expandBody verwenden.--maxDepth begrenzen. Der Standardwert ist 10.main.dot und passen Sie sie an.Authorization in OpenAPI-Codebeispielen. Wenn Sie dies weglassen möchten, lesen Sie hier.npm i um Abhängigkeiten zu installieren, odernpm install -g widdershins zur globalen InstallationWiddershins wird im Allgemeinen als Stufe in einer API-Dokumentationspipeline verwendet. Die Pipeline beginnt mit einer API-Definition im OpenAPI 3.x-, OpenAPI 2.0- (fka Swagger), API Blueprint-, AsyncAPI- oder Semoasa-Format. Widdershins wandelt diese Beschreibung in einen Markdown um, der für die Verwendung durch einen Renderer wie Slate, ReSlate, Shins ( veraltet ) oder HTML geeignet ist, der für die Verwendung mit ReSpec geeignet ist.
Wenn Sie Ihre Eingabe-API-Definition erstellen müssen, kann diese Liste der verfügbaren Editoren hilfreich sein.
Eine ausführlichere Dokumentation finden Sie hier.
node widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --summary defs/petstore3.json -o petstore3.md
| CLI-Parametername | Name des JavaScript-Parameters | Typ | Standardwert | Beschreibung |
|---|---|---|---|---|
| --Zwischenablage | Optionen.Zwischenablage | boolean | true | Legt den Wert der Eigenschaft code_clipboard in der Überschrift fest, sodass Markdown-Prozessoren die Unterstützung der Zwischenablage einschließen können. |
| --customApiKeyValue | Optionen.customApiKeyValue | string | ApiKey | Legen Sie einen benutzerdefinierten API-Schlüsselwert fest, der als API-Schlüssel in generierten Codebeispielen verwendet werden soll. |
| --expandBody | Optionen.expandBody | boolean | false | Wenn der requestBody-Parameter einer Methode per Referenz auf ein Schema verweist (nicht bei einem Inline-Schema), zeigt Widdershins standardmäßig nur eine Referenz auf diesen Parameter an. Setzen Sie diese Option auf „true“, um das Schema zu erweitern und alle Eigenschaften im Anforderungstext anzuzeigen. |
| --Überschriften | Optionen.Überschriften | integer | 2 | Legen Sie den Wert des headingLevel Parameters im Header fest, damit Markdown-Prozessoren wissen, wie viele Überschriftenebenen im Inhaltsverzeichnis angezeigt werden sollen. Wird derzeit nur von Shins unterstützt, nicht von Slate, dem diese Funktion fehlt. |
| --omitBody | Optionen.omitBody | boolean | false | Standardmäßig fügt Widdershins den Body-Parameter als Zeile in die Parametertabelle vor den Zeilen ein, die die Felder im Body darstellen. Legen Sie diesen Parameter fest, um diese Körperparameterzeile wegzulassen. |
| --omitHeader | Optionen.omitHeader | boolean | false | Lassen Sie den Header/YAML-Vorsatz in der generierten Markdown-Datei weg. |
| --lösen | Optionen.resolve | boolean | false | Lösen Sie externe $refs auf und verwenden Sie dabei den source oder die Eingabedatei als Basisspeicherort. |
| --shallowSchemas | Optionen.shallowSchemas | boolean | false | Wenn Sie mit einem $ref auf ein Schema verweisen, zeigen Sie nicht den vollständigen Inhalt des Schemas an. |
| N / A | Optionen.Quelle | string | Keiner | Der absolute Speicherort oder die URL der Quelldatei, die als Basis für die Auflösung relativer Referenzen ($refs) verwendet werden soll; erforderlich, wenn options.resolve auf true gesetzt ist. Für CLI-Befehle verwendet Widdershins die Eingabedatei als Basis für die $refs. |
| --Zusammenfassung | options.tocSummary | boolean | false | Verwenden Sie die Vorgangszusammenfassung als Inhaltsverzeichniseintrag anstelle der ID. |
| --useBodyName | Optionen.useBodyName | boolean | Verwenden Sie den ursprünglichen Parameternamen für den OpenAPI 2.0-Körperparameter. | |
| -v, --verbose | Optionen.verbose | boolean | false | Erhöhen Sie die Ausführlichkeit. |
| -h, --help | Optionen.Hilfe | boolean | false | Hilfe anzeigen. |
| --Version | Optionen.Version | boolean | false | Versionsnummer anzeigen. |
| -c, --code | Optionen.codeSamples | boolean | false | Lassen Sie generierte Codebeispiele weg. |
| --httpsnippet | Optionen.httpsnippet | boolean | false | Verwenden Sie httpsnippet, um Codebeispiele zu generieren. |
| -d, --discovery | Optionen.Discovery | boolean | false | Schließen Sie Schema.org-WebAPI-Erkennungsdaten ein. |
| -e, --environment | N / A | string | Keiner | Datei, aus der Konfigurationsoptionen geladen werden sollen. |
| -i, --includes | Optionen.includes | string | Keiner | Liste der Dateien, die in den include -Header des Ausgabe-Markdowns eingefügt werden sollen. Prozessoren wie Shins können dann den Inhalt dieser Dateien importieren. |
| -l, --lang | Optionen.lang | boolean | false | Generieren Sie die Liste der Sprachen für Codebeispiele basierend auf den Sprachen, die in den x-code-samples -Beispielen der Quelldatei verwendet werden. |
| --lingual_tabs | Optionen.Sprache_Tabs | string | (Unterschiedlich je nach Eingabetyp) | Liste der Sprachregisterkarten für Codebeispiele im Format language[:label[:client]], z. B. javascript:JavaScript:request . |
| -m, --maxDepth | Optionen.maxDepth | integer | 10 | Maximale Tiefe, die für Schemabeispiele angezeigt werden soll. |
| -o, --outfile | N / A | string | Keiner | Datei, in die der Ausgabe-Markdown geschrieben werden soll. Wenn das Feld leer bleibt, sendet Widdershins die Ausgabe an stdout. |
| -r, --raw | Umkehrung von options.sample | boolean | false | Geben Sie Rohschemata anstelle von Beispielwerten aus. |
| -s, --search | Optionen.Suche | boolean | true | Legen Sie den Wert des search im Header fest, damit Markdown-Prozessoren wie Slate die Suche in ihre Ausgabe einbeziehen oder nicht. |
| -t, --theme | Optionen.Theme | string | Darkula | Zu verwendendes Syntax-Highlighter-Theme. |
| -u, --user_templates | Optionen.user_templates | string | Keiner | Verzeichnis, aus dem Überschreibungsvorlagen geladen werden sollen. |
| -x, --experimental | Optionen.experimentell | boolean | Verwenden Sie httpSnippet für mehrteilige Medientypen. | |
| -y, --yaml | Optionen.yaml | boolean | false | Zeigen Sie JSON-Schemas im YAML-Format an. |
| Optionen.templateCallback | function | Keiner | Eine function , die vor und nach jeder Vorlage aufgerufen wird (nur JavaScript-Code). | |
| Optionen.toc_footers | object | Eine Zuordnung von url und description , die dem ToC-Fußzeilen-Array hinzugefügt werden sollen (nur JavaScript-Code). |
Erstellen Sie im Node.JS-Code ein Optionsobjekt und übergeben Sie es an die convert von Widdershins, wie in diesem Beispiel:
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 ) ;
} ) ; Um nur eine Teilmenge der vordefinierten Sprachregisterkarten einzuschließen oder deren Anzeigenamen umzubenennen, können Sie die options.language_tabs . language_tabs überschreiben:
options . language_tabs = [ { 'go' : 'Go' } , { 'http' : 'HTTP' } , { 'javascript' : 'JavaScript' } , { 'javascript--node' : 'Node.JS' } , { 'python' : 'Python' } , { 'ruby' : 'Ruby' } ] ; Die Option --environment gibt ein JSON- oder YAML-formatiertes options an, zum Beispiel:
{
"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 " ]
}
]
}Sie können die Umgebungsdatei auch verwenden, um mit OAS/Swagger markierte Pfade zu gruppieren und so ein eleganteres Inhaltsverzeichnis und eine insgesamt elegantere Seitenstruktur zu erstellen.
Wenn Sie eine Version von Slate <v1.5.0 (oder einen Renderer, der auch keine Anzeigenamen für Sprachregisterkarten unterstützt, wie z. B. node-slate , slate-node oder whiteboard ) unterstützen müssen, können Sie --environment verwenden. Um dies einfach zu erreichen, können Sie die --environment mit der enthaltenen Datei whiteboard_env.json verwenden.
Wenn Sie die httpsnippet Option zum Generieren von Codebeispielen verwenden, können Sie die Client-Bibliothek angeben, die zum Ausführen der Anforderungen für jede Sprache verwendet wird, indem Sie options.language_clients . language_clients überschreiben:
options . language_clients = [ { 'shell' : 'curl' } , { 'node' : 'request' } , { 'java' : 'unirest' } ] ; Wenn sich der Sprachname zwischen dem zur Syntaxhervorhebung erforderlichen Markdown-Namen und dem erforderlichen httpsnippet-Ziel unterscheidet, können beide in der Form markdown--target angegeben werden.
Klicken Sie hier, um die Liste der von httpsnippet unterstützten Sprachen und Clients anzuzeigen.
Die Option loadedFrom wird nur benötigt, wenn die OpenAPI-/Swagger-Definition keinen Host angibt und (gemäß der OpenAPI-Spezifikation) davon ausgegangen wird, dass der API-Endpunkt auf der Quell-URL basiert, von der die Definition geladen wurde.
Klicken Sie hier, um die Liste der Highlight-JS-Syntaxhervorhebungsthemen anzuzeigen.
Schema.org-WebAPI-Erkennungsdaten sind enthalten, wenn die obige discovery auf true gesetzt ist. Weitere Informationen finden Sie in der W3C WebAPI Discovery Community Group.
Widdershins unterstützt die Herstellererweiterung x-code-samples um Ihre Dokumentation vollständig anzupassen. Alternativ können Sie die Standardcodebeispiele im Unterverzeichnis templates bearbeiten oder sie mit der Option user_templates überschreiben, um ein Verzeichnis mit Ihren Vorlagen anzugeben.
Widdershins unterstützt die Verwendung mehrerer Sprachregisterkarten mit derselben Sprache (z. B. einfaches Javascript und Node.Js). Um diese Unterstützung nutzen zu können, müssen Sie Slate (oder einen seiner damit kompatiblen Ports) Version 1.5.0 oder höher verwenden.
Standardmäßig verwendet Widdershins die Vorlagen in seinem templates/ -Ordner, um die Markdown-Ausgabe zu generieren. Um die Vorlagen anzupassen, kopieren Sie einige oder alle davon in einen Ordner und übergeben Sie ihren Speicherort an den Parameter user_templates .
Zu den Vorlagen gehören .dot Vorlagen und .def Teilvorlagen. Um eine .dot Vorlage zu überschreiben, müssen Sie sie und die untergeordneten .def Teildateien, auf die die Vorlage verweist, kopieren. Ebenso müssen Sie zum Überschreiben einer .def Teilvorlage auch die übergeordnete .dot Vorlage kopieren. Für OpenAPI 3 ist die primäre Vorlage main.dot und die wichtigsten untergeordneten Teilvorlagen sind parameters.def , responses.def und callbacks.def “.
Dies bedeutet, dass es normalerweise am einfachsten ist, alle .dot und .def Dateien in Ihr Benutzervorlagenverzeichnis zu kopieren, damit Sie keine Vorlage oder einen Teil davon überspringen. Um Änderungen aus Widdershins-Updates einzubringen, können Sie ein visuelles diff -Tool verwenden, das in zwei Verzeichnissen ausgeführt werden kann, z. B. Meld oder WinMerge.
Vorlagen werden mit doT.js kompiliert.
Vorlagen haben Zugriff auf ein data mit einer Reihe von Eigenschaften basierend auf dem Dokumentkontext. Informationen zu den Parametern finden Sie in der README-Datei für die entsprechenden Vorlagen:
Um den Wert eines Parameters oder einer Variablen in einer Vorlage zu drucken, verwenden Sie den Code {{=parameterName}} . Um beispielsweise den Titel einer OpenAPI 3-Spezifikation (aus dem Feld info.title ) auszudrucken, verwenden Sie den Code {{=data.api.info.title}} .
Um Werte in einem Array zu durchlaufen, verwenden Sie den Code {{~ arrayName :tempVariable}} um die Schleife zu starten, und den Code {{~}} um die Schleife zu schließen. Beispielsweise verwendet die OpenAPI 3- parameters.def diesen Code, um eine Tabelle der Parameter in einer Operation zu erstellen:
|Name|In|Type|Required|Description|
|---|---|---|---|---|
{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{=p.safeType}}|{{=p.required}}|{{=p.shortDesc || 'none'}}|
{{~}}
Verwenden Sie für die Wenn/Dann-Logik den Code {{? booleanExpression}} zum Starten des Codeblocks und den Code {{?}} zum Schließen des Blocks. Beispielsweise ruft die Vorlage main.dot von OpenAPI 3 den Teil security.def auf, um Informationen zu den Sicherheitsschemata anzuzeigen, wenn die OpenAPI-Spezifikation einen Abschnitt securitySchemes enthält:
{{? data.api.components && data.api.components.securitySchemes }}
{{#def.security}}
{{?}}
Sie können beliebiges JavaScript innerhalb einer Vorlage ausführen, indem Sie einen Codeblock in geschweifte Klammern einfügen. Dieser Code erstellt beispielsweise eine Variable und referenziert sie später in der Vorlage mit der normalen doT.js-Syntax:
{{ {
let message = "Hello!";
} }}
{{=message}}
Der Parameter templateCallback verweist auf eine Funktion, die Widdershins vor und nach der Ausführung jeder Vorlage aufruft. Die Rückruffunktion empfängt ein data , das die Spezifikation enthält, die Widdershins verarbeitet; Die Funktion muss dieses Objekt zurückgeben. Sie können Rückruffunktionen nur verwenden, wenn Sie Widdershins über JavaScript-Code und nicht über die Befehlszeile aufrufen.
Widdershins übergibt diese Variablen an die Callback-Funktion:
templateName : Der Name der Vorlage, z. B. main .stage : Ob Widdershins die Callback-Funktion vor ( pre ) oder nach ( post ) der Vorlage aufruft.data : Ein Objekt, das die Daten enthält, die Widdershins verarbeitet. Sie können das data nach Belieben ändern, die Funktion muss es jedoch zurückgeben, unabhängig davon, ob sie es ändert oder nicht. Inhalte, die Sie in die data.append -Eigenschaft einfügen, werden an den aktuellen Ausgabestream angehängt.Dieser JavaScript-Code gibt beispielsweise den Namen der Vorlage und die Verarbeitungsstufe im Ausgabe-Markdown aus:
'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' ) ;
} ) ; So führen Sie eine Testsuite aus:
node testRunner {path-to-APIs}
Die Testumgebung erwartet derzeit .yaml oder .json Dateien und wurde anhand dieser Dateien getestet
Blogbeitrag des Autors von Widdershins.
Fügen Sie hier gerne einen Link zu Ihrer API-Dokumentation hinzu.
Widdershins funktioniert gut mit Slate, aber für ein ausschließlich Node.js-basiertes Erlebnis probieren Sie doch mal den ReSlate-Port aus.
