widdershins

OpenApi / Swagger definition to Slate / Shins compatible markdown

Widdershins adverb:

• In a direction contrary to the sun's course;
• anticlockwise;
• helping you produce static documentation from your OpenApi / Swagger 2.0 definition

Widdershins supports the x-code-samples vendor-extension to completely customise your documentation. Alternatively, you can edit the default code-samples in the templates sub-directory, or override them using the user_templates option to specify a directory containing your templates.

To install

• Clone the git repository, or
• npm install widdershins, or
• yarn global add widdershins

node widdershins [options] {input-spec} [[-o] output markdown]

Options:
  -h, --help     Show help                                             [boolean]
  --version      Show version number                                   [boolean]
  -y, --yaml     Load spec in yaml format, default json                [boolean]
  -c, --code     Turn generic code samples off                         [boolean]
  -l, --lang     Automatically generate list of languages for code samples
                                                                       [boolean]
  -o, --outfile  file to write output markdown to                       [string]
  -t, --theme    Syntax-highlighter theme to use                        [string]

or

var converter = require('widdershins');
var options = {}; // defaults shown
options.codeSamples = true;
//options.language_tabs = [];
//options.loadedFrom = sourceUrl;
//options.user_templates = './user_templates';
options.theme = 'darkula';
var str = converter.convert(swaggerObj,options);

loadedFrom option is only needed where the OpenApi / Swagger definition does not specify a host, and (as per the OpenApi specification) the API endpoint is deemed to be based on the source URL the definition was loaded from.

To see the list of highlight-js syntax highlighting themes, click here

Template parameters

Templates are compiled with doT.js.

Templates have access to a data object with a range of properties based on the document context.

Code templates

• method - the HTTP method of the operation (in lower-case)
• methodUpper - the HTTP method of the operation (in upper-case)
• url - the full URL of the operation (including protocol and host)
• parameters[] - an array of parameters for the operation
• consumes[] - an array of MIME-types the operation consumes
• produces[] - an array of MIME-types the operation produces
• operation - the current operation object
• operationId - the current operation id
• tags[] - the full list of tags applying to the operation
• resource - the current tag/path object

Parameter template

• parameters[] - an array of parameters, including a shortDesc property
• enums[] - an array of (parameter)name/value pairs

Responses template

• responses[] - an array of responses, including status and meaning properties

Authentication template

• authenticationStr - a simple string of methods (and scopes where appropriate)
• securityDefinitions[] - an array of applicable securityDefinitions

Common to all templates

• openapi - the top-level OpenApi / Swagger document
• header - the front-matter of the Slate/Shins markdown document
• host - the (computed) host of the API
• protocol - the default/first protocol of the API
• baseUrl - the (computed) baseUrl of the API (including protocol and host)

Tests

To run a test-suite:

node testRunner {path-to-APIs}

The test harness currently expects files named swagger.yaml or swagger.json and has been tested against

• APIs.guru
• Mermade OpenApi specifications collection

Comparison between this and other OpenAPI / Swagger to Slate tools

Blog posting by the author of Widdershins

Acknowledgements

Thanks to @latgeek for the logo.