widdershins Télécharger - widdershins Téléchargement du code source

widdershins

Autre code source

v4.0.0

Télécharger

les tibias plus larges

Définition OpenAPI / Swagger / AsyncAPI / Semoasa vers démarque compatible Slate / ReSlate

Adverbe de Widdershins :

Dans une direction contraire à la course du soleil ;
dans le sens inverse des aiguilles d'une montre ;
vous aidant à produire une documentation statique à partir de votre définition OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0

Nouvelles

Modifications de la version 4.0 :
- Utilise désormais les promesses et non les rappels
- Option pour sortir directement le HTML et au format ReSpec
- Exemples de code JavaScript et Node.js unifiés, PHP ajouté
- colonne restrictions ( readOnly / writeOnly ) ajoutée aux modèles de schéma
- De nombreuses corrections de bugs
Depuis la version 3.0.0, Widdershins n'étend plus la définition des paramètres de corps / requestBodies OpenAPI par défaut, à moins qu'ils n'aient un schéma en ligne. Vous pouvez restaurer l'ancien comportement en utilisant l'option --expandBody .
Vous pouvez limiter la profondeur des exemples de schéma en utilisant l'option --maxDepth . La valeur par défaut est 10.
Pour omettre complètement les schémas, veuillez copier et personnaliser le modèle main.dot .
Depuis la version 3.1.0, Widdershins inclut un en-tête Authorization généré dans les exemples de code OpenAPI. Si vous souhaitez omettre cela, voyez ici.

Pour installer

Clonez le référentiel git et npm i pour installer les dépendances, ou
npm install -g widdershins à installer globalement

Commencer

Widdershins est généralement utilisé comme étape dans un pipeline de documentation API. Le pipeline commence par une définition d'API au format OpenAPI 3.x, OpenAPI 2.0 (anciennement Swagger), API Blueprint, AsyncAPI ou Semoasa. Widdershins convertit cette description en markdown adapté à une utilisation par un moteur de rendu , tel que Slate, ReSlate, Shins ( obsolète ) ou en HTML adapté à une utilisation avec ReSpec.

Si vous devez créer votre définition d'API d'entrée, cette liste d'éditeurs disponibles peut être utile.

Une documentation plus approfondie est disponible ici.

Exemples

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

Possibilités

Nom du paramètre CLI	Nom du paramètre JavaScript	Taper	Valeur par défaut	Description
--presse-papiers	options.clipboard	`boolean`	`true`	Définit la valeur de la propriété `code_clipboard` dans l'en-tête, afin que les processeurs de démarques puissent inclure la prise en charge du presse-papiers.
--customApiKeyValue	options.customApiKeyValue	`string`	`ApiKey`	Définissez une valeur de clé API personnalisée à utiliser comme clé API dans les exemples de code générés.
--expandBody	options.expandBody	`boolean`	`false`	Si le paramètre requestBody d'une méthode fait référence à un schéma par référence (et non avec un schéma en ligne), par défaut, Widdershins affiche uniquement une référence à ce paramètre. Définissez cette option sur true pour développer le schéma et afficher toutes les propriétés dans le corps de la demande.
--titres	options.headings	`integer`	2	Définissez la valeur du paramètre `headingLevel` dans l'en-tête afin que les processeurs de démarques sachent combien de niveaux de titre afficher dans la table des matières. Actuellement pris en charge uniquement par Shins, pas par Slate, qui ne dispose pas de cette fonctionnalité.
--omitCorps	options.omitBody	`boolean`	`false`	Par défaut, Widdershins inclut le paramètre body sous forme de ligne dans le tableau des paramètres avant les lignes qui représentent les champs du corps. Définissez ce paramètre pour omettre cette ligne de paramètres de corps.
--omitEn-tête	options.omitHeader	`boolean`	`false`	Omettez l’en-tête/le front-matter YAML dans le fichier Markdown généré.
--résoudre	options.resolve	`boolean`	`false`	Résolvez les $refs externes, en utilisant le paramètre `source` ou le fichier d'entrée comme emplacement de base.
--shallowSchemas	options.shallowSchemas	`boolean`	`false`	Lorsque vous faites référence à un schéma avec $ref, n'affichez pas le contenu complet du schéma.
N / A	options.source	`string`	Aucun	L'emplacement absolu ou l'URL du fichier source à utiliser comme base pour résoudre les références relatives ($refs) ; requis si options.resolve est défini sur true. Pour les commandes CLI, Widdershins utilise le fichier d'entrée comme base pour les $refs.
--résumé	options.tocRésumé	`boolean`	`false`	Utilisez le résumé de l'opération comme entrée de la table des matières au lieu de l'ID.
--useBodyName	options.useBodyName	`boolean`	Utilisez le nom du paramètre d'origine pour le paramètre de corps OpenAPI 2.0.
-v, --verbeux	options.verbeux	`boolean`	`false`	Augmentez la verbosité.
-h, --aide	options.aide	`boolean`	`false`	Afficher l'aide.
--version	options.version	`boolean`	`false`	Afficher le numéro de version.
-c, --code	options.codeSamples	`boolean`	`false`	Omettez les exemples de code générés.
--httpsnippet	options.httpsnippet	`boolean`	`false`	Utilisez httpsnippet pour générer des exemples de code.
-d, --découverte	options.découverte	`boolean`	`false`	Incluez les données de découverte schema.org WebAPI.
-e, --environnement	N / A	`string`	Aucun	Fichier à partir duquel charger les options de configuration.
-i, --inclut	options.inclut	`string`	Aucun	Liste des fichiers à mettre dans l'en-tête d' `include` du Markdown de sortie. Des processeurs tels que Shins peuvent ensuite importer le contenu de ces fichiers.
-l, --lang	options.lang	`boolean`	`false`	Générez la liste des langues pour les exemples de code en fonction des langues utilisées dans les exemples `x-code-samples` du fichier source.
--langue_tabs	options.langue_tabs	`string`	(Diffère pour chaque type d'entrée)	Liste des onglets de langue pour les exemples de code utilisant le format language[:label[:client]], tel que `javascript:JavaScript:request` .
-m, --maxDepth	options.maxDepth	`integer`	10	Profondeur maximale à afficher pour les exemples de schéma.
-o, --fichier de sortie	N / A	`string`	Aucun	Fichier dans lequel écrire la démarque de sortie. Si laissé vide, Widdershins envoie la sortie vers la sortie standard.
-r, --brut	inverse d'options.sample	`boolean`	`false`	Générez des schémas bruts au lieu d’exemples de valeurs.
-s, --recherche	options.recherche	`boolean`	`true`	Définissez la valeur du paramètre `search` dans l'en-tête afin que les processeurs Markdown comme Slate incluent ou non la recherche dans leur sortie.
-t, --thème	options.thème	`string`	darkula	Thème de surligneur de syntaxe à utiliser.
-u, --user_templates	options.user_templates	`string`	Aucun	Répertoire à partir duquel charger les modèles de remplacement.
-x, --expérimental	options.expérimental	`boolean`		Utilisez httpSnippet pour les types de médias en plusieurs parties.
-y, --yaml	options.yaml	`boolean`	`false`	Affichez les schémas JSON au format YAML.
	options.templateCallback	`function`	Aucun	Une `function` appelée avant et après chaque modèle (code JavaScript uniquement).
	options.toc_footers	`object`	Une carte des `url` et `description` à ajouter au tableau de pieds de page ToC (code JavaScript uniquement).

Dans le code Node.JS, créez un objet options et transmettez-le à la fonction convert Widdershins, comme dans cet exemple :

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

Pour inclure uniquement un sous-ensemble des onglets de langue prédéfinis, ou pour renommer leurs noms d'affichage, vous pouvez remplacer les options.language_tabs :

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

L'option --environment spécifie un objet options au format JSON ou YAML, par exemple :

{
  "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 " ]
    }
  ]
}

Vous pouvez également utiliser le fichier d'environnement pour regrouper les chemins balisés OAS/Swagger afin de créer une table des matières plus élégante et une structure globale de page.

Si vous devez prendre en charge une version de Slate <v1.5.0 (ou un moteur de rendu qui ne prend pas non plus en charge les noms d'affichage pour les onglets de langue, tels que node-slate , slate-node ou whiteboard ), vous pouvez utiliser le --environment option --environment avec le fichier whiteboard_env.json inclus pour y parvenir simplement.

Si vous utilisez l'option httpsnippet pour générer des exemples de code, vous pouvez spécifier la bibliothèque client utilisée pour effectuer les requêtes pour chaque langue en remplaçant options.language_clients :

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

Si le nom de la langue diffère entre le nom de démarque requis pour la mise en évidence de la syntaxe et la cible httpsnippet requise, les deux peuvent être spécifiés sous la forme markdown--target .

Pour voir la liste des langues et des clients pris en charge par httpsnippet, cliquez ici.

L' loadedFrom n'est nécessaire que lorsque la définition OpenAPI/Swagger ne spécifie pas d'hôte et (conformément à la spécification OpenAPI) le point de terminaison de l'API est considéré comme étant basé sur l'URL source à partir de laquelle la définition a été chargée.

Pour voir la liste des thèmes de coloration syntaxique highlight-js, cliquez ici.

Les données de découverte Schema.org WebAPI sont incluses si l'option discovery ci-dessus est définie true . Consultez le groupe communautaire W3C WebAPI Discovery pour plus d’informations.

Onglets de langue

Widdershins prend en charge l'extension du fournisseur x-code-samples pour personnaliser complètement votre documentation. Vous pouvez également modifier les exemples de code par défaut dans le sous-répertoire templates ou les remplacer à l'aide de l'option user_templates pour spécifier un répertoire contenant vos modèles.

Widdershins prend en charge l'utilisation de plusieurs onglets de langue avec le même langage (c'est-à-dire Javascript simple et Node.Js). Pour utiliser ce support, vous devez utiliser Slate (ou l'un de ses ports compatible avec) version 1.5.0 ou supérieure.

Modèles

Par défaut, Widdershins utilise les modèles de son dossier templates/ pour générer la sortie Markdown. Pour personnaliser les modèles, copiez-en tout ou partie dans un dossier et transmettez leur emplacement au paramètre user_templates .

Les modèles incluent des modèles .dot et des partiels .def . Pour remplacer un modèle .dot , vous devez le copier ainsi que les partiels .def enfants auxquels le modèle fait référence. De même, pour remplacer un partiel .def , vous devez également copier le modèle .dot parent. Pour OpenAPI 3, le modèle principal est main.dot et ses principaux partiels enfants sont parameters.def , responses.def et callbacks.def .

Cela signifie qu'il est généralement plus simple de copier tous les fichiers .dot et .def dans votre répertoire de modèles utilisateur afin de ne pas ignorer un modèle ou une partie. Pour apporter des modifications à partir des mises à jour de Widdershins, vous pouvez utiliser un outil diff visuelle qui peut s'exécuter sur deux répertoires, tel que Meld ou WinMerge.

Syntaxe du modèle

Les modèles sont compilés avec doT.js.

Les modèles ont accès à un objet data avec une gamme de propriétés basées sur le contexte du document. Pour plus d'informations sur les paramètres, consultez le fichier README pour les modèles appropriés :

Paramètres du modèle Swagger 2.0 / OpenAPI 3.0.x
Paramètres du modèle AsyncAPI 1.x
Paramètres du modèle Semoasa 0.1.0

Pour imprimer la valeur d'un paramètre ou d'une variable dans un modèle, utilisez le code {{=parameterName}} . Par exemple, pour imprimer le titre d'une spécification OpenAPI 3 (à partir de son champ info.title ), utilisez le code {{=data.api.info.title}} .

Pour parcourir les valeurs d'un tableau, utilisez le code {{~ arrayName :tempVariable}} pour démarrer la boucle et le code {{~}} pour fermer la boucle. Par exemple, le fichier partiel parameters.def d'OpenAPI 3 utilise ce code pour créer une table des paramètres dans une opération :

 |Name|In|Type|Required|Description|
|---|---|---|---|---|
{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{=p.safeType}}|{{=p.required}}|{{=p.shortDesc || 'none'}}|
{{~}}

Pour la logique si/alors, utilisez le code {{? booleanExpression}} pour démarrer le bloc de code et le code {{?}} pour fermer le bloc. Par exemple, le modèle main.dot d'OpenAPI 3 appelle le partiel security.def pour afficher des informations sur les schémas de sécurité si la spécification OpenAPI inclut une section securitySchemes :

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

Vous pouvez exécuter du JavaScript arbitraire dans un modèle en insérant un bloc de code entre accolades. Par exemple, ce code crée une variable et la référence avec la syntaxe doT.js normale plus loin dans le modèle :

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

{{=message}}

Rappels de modèles

Le paramètre templateCallback pointe vers une fonction que Widdershins appelle avant et après l'exécution de chaque modèle. La fonction de rappel reçoit un objet data qui contient la spécification traitée par Widdershins ; la fonction doit renvoyer cet objet. Vous pouvez utiliser les fonctions de rappel uniquement si vous appelez Widdershins à partir du code JavaScript, et non à partir de la ligne de commande.

Widdershins transmet ces variables à la fonction de rappel :

templateName : Le nom du modèle, tel que main .
stage : indique si Widdershins appelle la fonction de rappel avant ( pre ) ou après ( post ) le modèle.
data : Un objet qui contient les données que Widdershins traite. Vous pouvez muter l'objet data comme bon vous semble, mais la fonction doit le renvoyer, qu'elle le modifie ou non. Le contenu que vous placez dans la propriété data.append est ajouté au flux de sortie actuel.

Par exemple, ce code JavaScript imprime le nom du modèle et l'étape de traitement dans le Markdown de sortie :

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