Descarga de widdershins - Descarga del código fuente widdershins

widdershins

Otro código fuente

v4.0.0

Descargar

espinillas anchas

OpenAPI / Swagger / AsyncAPI / Definición de Semoasa para rebajas compatibles con Slate / ReSlate

Widdershins adverbio :

En dirección contraria al curso del sol;
sinistrorso;
ayudándole a producir documentación estática a partir de su definición de OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0

Noticias

Cambios en la versión 4.0:
- Ahora usa Promesas, no devoluciones de llamada.
- Opción para generar html directamente y en formato ReSpec
- Ejemplos de código unificados de JavaScript y Node.js, PHP agregado
- columna restrictions ( readOnly / writeOnly ) agregada a las plantillas de esquema
- Numerosas correcciones de errores
A partir de la versión 3.0.0, Widdershins ya no amplía la definición de los parámetros del cuerpo OpenAPI/solicitudBodies de forma predeterminada, a menos que tengan un esquema en línea. Puede restaurar el comportamiento anterior utilizando la opción --expandBody .
Puede limitar la profundidad de los ejemplos de esquema utilizando la opción --maxDepth . El valor predeterminado es 10.
Para omitir esquemas por completo, copie y personalice la plantilla main.dot .
A partir de la versión 3.1.0, Widdershins incluye un encabezado Authorization generado en ejemplos de código OpenAPI. Si desea omitir esto, consulte aquí.

Para instalar

Clonar el repositorio de git y npm i para instalar dependencias, o
npm install -g widdershins para instalar globalmente

Empezando

Widdershins se utiliza generalmente como etapa en un proceso de documentación de API. El proceso comienza con una definición de API en formato OpenAPI 3.x, OpenAPI 2.0 (antes Swagger), API Blueprint, AsyncAPI o Semoasa. Widdershins convierte esta descripción en una reducción adecuada para su uso por parte de un renderizador , como Slate, ReSlate, Shins ( en desuso ) o html adecuado para su uso con ReSpec.

Si necesita crear su definición de API de entrada, esta lista de editores disponibles puede resultarle útil.

Hay documentación más detallada disponible aquí.

Ejemplos

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

Opciones

Nombre del parámetro CLI	Nombre del parámetro JavaScript	Tipo	Valor predeterminado	Descripción
--portapapeles	opciones.portapapeles	`boolean`	`true`	Establece el valor de la propiedad `code_clipboard` en el encabezado, para que los procesadores de rebajas puedan incluir soporte para portapapeles.
--customApiKeyValue	opciones.customApiKeyValue	`string`	`ApiKey`	Establezca un valor de clave API personalizado para utilizarlo como clave API en los ejemplos de código generado.
--expandirCuerpo	opciones.expandirCuerpo	`boolean`	`false`	Si el parámetro requestBody de un método hace referencia a un esquema por referencia (no con un esquema en línea), de forma predeterminada, Widdershins muestra solo una referencia a este parámetro. Establezca esta opción en verdadero para expandir el esquema y mostrar todas las propiedades en el cuerpo de la solicitud.
--encabezados	opciones.encabezados	`integer`	2	Establezca el valor del parámetro `headingLevel` en el encabezado para que los procesadores de rebajas sepan cuántos niveles de encabezado mostrar en la tabla de contenido. Actualmente sólo es compatible con Shins, no con Slate, que carece de esta característica.
--omitirCuerpo	opciones.omitBody	`boolean`	`false`	De forma predeterminada, Widdershins incluye el parámetro del cuerpo como una fila en la tabla de parámetros antes de las filas que representan los campos del cuerpo. Establezca este parámetro para omitir esa fila de parámetros del cuerpo.
--omitEncabezado	opciones.omitHeader	`boolean`	`false`	Omita el encabezado / portada YAML en el archivo Markdown generado.
--resolver	opciones.resolver	`boolean`	`false`	Resuelva $refs externos, utilizando el parámetro `source` o el archivo de entrada como ubicación base.
--esquemas superficiales	opciones.shallowSchemas	`boolean`	`false`	Cuando haga referencia a un esquema con $ref, no muestre el contenido completo del esquema.
N / A	opciones.fuente	`string`	Ninguno	La ubicación absoluta o URL del archivo fuente que se utilizará como base para resolver referencias relativas ($refs); requerido si options.resolve se establece en verdadero. Para los comandos CLI, Widdershins utiliza el archivo de entrada como base para $refs.
--resumen	options.tocResumen	`boolean`	`false`	Utilice el resumen de la operación como entrada TOC en lugar del ID.
--useNombreCuerpo	opciones.useBodyName	`boolean`	Utilice el nombre del parámetro original para el parámetro del cuerpo de OpenAPI 2.0.
-v, --detallado	opciones.detallado	`boolean`	`false`	Aumentar la verbosidad.
-h, --ayuda	opciones.ayuda	`boolean`	`false`	Mostrar ayuda.
--versión	opciones.version	`boolean`	`false`	Mostrar número de versión.
-c, --código	opciones.codeMuestras	`boolean`	`false`	Omita los ejemplos de código generado.
--httpsnippet	opciones.httpsnippet	`boolean`	`false`	Utilice httpsnippet para generar ejemplos de código.
-d, --descubrimiento	opciones.descubrimiento	`boolean`	`false`	Incluya datos de descubrimiento de WebAPI de Schema.org.
-e, --entorno	N / A	`string`	Ninguno	Archivo desde el que cargar las opciones de configuración.
-yo, --incluye	opciones.incluye	`string`	Ninguno	Lista de archivos para colocar en el encabezado de `include` del Markdown de salida. Los procesadores como Shins pueden importar el contenido de estos archivos.
-l, --lang	opciones.lang	`boolean`	`false`	Genere la lista de idiomas para ejemplos de código en función de los idiomas utilizados en los ejemplos de `x-code-samples` del archivo fuente.
--lenguaje_tabs	opciones.idioma_tabs	`string`	(Difiere para cada tipo de entrada)	Lista de pestañas de idioma para ejemplos de código que utilizan el formato language[:label[:client]], como `javascript:JavaScript:request` .
-m, --maxProfundidad	opciones.maxDepth	`integer`	10	Profundidad máxima que se mostrará en los ejemplos de esquemas.
-o, --archivo de salida	N / A	`string`	Ninguno	Archivo en el que escribir la rebaja de salida. Si se deja en blanco, Widdershins envía la salida a la salida estándar.
-r, --crudo	inverso de opciones.muestra	`boolean`	`false`	Genere esquemas sin formato en lugar de valores de ejemplo.
-s, --buscar	opciones.buscar	`boolean`	`true`	Establezca el valor del parámetro `search` en el encabezado para que los procesadores Markdown como Slate incluyan la búsqueda o no en su salida.
-t, --tema	opciones.tema	`string`	oscuro	Tema resaltador de sintaxis a utilizar.
-u, --plantillas_usuario	opciones.user_templates	`string`	Ninguno	Directorio desde el que cargar plantillas de anulación.
-x, --experimental	opciones.experimental	`boolean`		Utilice httpSnippet para tipos de medios de varias partes.
-y, --yaml	opciones.yaml	`boolean`	`false`	Muestra esquemas JSON en formato YAML.
	opciones.templateCallback	`function`	Ninguno	Una `function` que se llama antes y después de cada plantilla (solo código JavaScript).
	opciones.toc_footers	`object`	Un mapa de `url` y `description` que se agregarán a la matriz de pies de página de ToC (solo código JavaScript).

En el código Node.JS, cree un objeto de opciones y páselo a la función convert de Widdershins, como en este ejemplo:

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

Para incluir solo un subconjunto de las pestañas de idioma predefinidas, o cambiar el nombre de sus nombres para mostrar, puede anular options.language_tabs :

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

La opción --environment especifica un objeto options con formato JSON o YAML, por ejemplo:

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

También puede utilizar el archivo de entorno para agrupar las rutas etiquetadas de OAS/Swagger para crear una tabla de contenidos y una estructura general de la página más elegantes.

Si necesita admitir una versión de Slate <v1.5.0 (o un procesador que tampoco admite nombres para mostrar para pestañas de idiomas, como node-slate , slate-node o whiteboard ), puede usar --environment opción --environment con el archivo whiteboard_env.json incluido para lograr esto simplemente.

Si está utilizando la opción httpsnippet para generar ejemplos de código, puede especificar la biblioteca cliente utilizada para realizar las solicitudes para cada idioma anulando options.language_clients :

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

Si el nombre del idioma difiere entre el nombre de Markdown requerido para resaltar la sintaxis y el destino requerido del httpsnippet, ambos se pueden especificar en el formato markdown--target .

Para ver la lista de idiomas y clientes admitidos por httpsnippet, haga clic aquí.

La opción loadedFrom solo es necesaria cuando la definición de OpenAPI/Swagger no especifica un host y (según la especificación de OpenAPI) se considera que el punto final de la API se basa en la URL de origen desde la que se cargó la definición.

Para ver la lista de temas de resaltado de sintaxis de Highlight-js, haga clic aquí.

Los datos de descubrimiento de Schema.org WebAPI se incluyen si la opción discovery anterior está configurada true . Consulte el grupo comunitario de descubrimiento de WebAPI del W3C para obtener más información.

Pestañas de idioma

Widdershins admite la extensión de proveedor x-code-samples para personalizar completamente su documentación. Alternativamente, puede editar los ejemplos de código predeterminados en el subdirectorio templates o anularlos usando la opción user_templates para especificar un directorio que contenga sus plantillas.

Widdershins admite el uso de múltiples pestañas de idiomas con el mismo idioma (es decir, Javascript simple y Node.Js). Para utilizar este soporte debe utilizar Slate (o uno de sus puertos compatibles) versión 1.5.0 o superior.

Plantillas

De forma predeterminada, Widdershins usa las plantillas en su carpeta templates/ para generar la salida de Markdown. Para personalizar las plantillas, copie algunas o todas a una carpeta y pase su ubicación al parámetro user_templates .

Las plantillas incluyen plantillas .dot y parciales .def . Para anular una plantilla .dot , debe copiarla y los parciales .def secundarios a los que hace referencia la plantilla. De manera similar, para anular un parcial .def , también debe copiar la plantilla .dot principal. Para OpenAPI 3, la plantilla principal es main.dot y sus parciales secundarios principales son parameters.def , responses.def y callbacks.def .

Esto significa que normalmente es más fácil copiar todos los archivos .dot y .def a su directorio de plantillas de usuario para no omitir una plantilla o parte de ella. Para incorporar cambios de las actualizaciones de Widdershins, puede utilizar una herramienta diff visual que puede ejecutarse en dos directorios, como Meld o WinMerge.

Sintaxis de plantilla

Las plantillas se compilan con doT.js.

Las plantillas tienen acceso a un objeto data con una variedad de propiedades según el contexto del documento. Para obtener información sobre los parámetros, consulte el archivo README para obtener las plantillas adecuadas:

Parámetros de plantilla Swagger 2.0/OpenAPI 3.0.x
Parámetros de la plantilla AsyncAPI 1.x
Parámetros de la plantilla Semoasa 0.1.0

Para imprimir el valor de un parámetro o variable en una plantilla, use el código {{=parameterName}} . Por ejemplo, para imprimir el título de una especificación OpenAPI 3 (desde su campo info.title ), use el código {{=data.api.info.title}} .

Para recorrer los valores en una matriz, use el código {{~ arrayName :tempVariable}} para iniciar el ciclo y el código {{~}} para cerrar el ciclo. Por ejemplo, el parameters.def parcial de OpenAPI 3.def usa este código para crear una tabla de parámetros en una operación:

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

Para la lógica si/entonces, use el código {{? booleanExpression}} para iniciar el bloque de código y el código {{?}} para cerrar el bloque. Por ejemplo, la plantilla main.dot de OpenAPI 3 llama al parcial security.def para mostrar información sobre los esquemas de seguridad si la especificación de OpenAPI incluye una sección securitySchemes :

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

Puede ejecutar JavaScript arbitrario dentro de una plantilla insertando un bloque de código entre llaves. Por ejemplo, este código crea una variable y hace referencia a ella con la sintaxis normal de doT.js más adelante en la plantilla:

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

{{=message}}

Devoluciones de llamada de plantilla

El parámetro templateCallback apunta a una función que Widdershins llama antes y después de que se ejecute cada plantilla. La función de devolución de llamada recibe un objeto data que contiene la especificación que Widdershins está procesando; la función debe devolver este objeto. Puede usar funciones de devolución de llamada solo si llama a Widdershins desde código JavaScript, no desde la línea de comando.

Widdershins pasa estas variables a la función de devolución de llamada:

templateName : el nombre de la plantilla, como main .
stage : si Widdershins está llamando a la función de devolución de llamada antes ( pre ) o después ( post ) de la plantilla.
data : un objeto que contiene los datos que Widdershins está procesando. Puede mutar el objeto data de la forma que considere adecuada, pero la función debe devolverlo, lo cambie o no. El contenido que coloca en la propiedad data.append se agrega al flujo de salida actual.

Por ejemplo, este código JavaScript imprime el nombre de la plantilla y la etapa de procesamiento en el Markdown de salida:

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