OpenApi / Swagger definition to Slate / Shins compatible markdown
- 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.
Widdershins supports the use of multiple language tabs with the same language (i.e. plain Javascript and Node.Js). To use this support you must be using Slate (or one of its ports compatible with) version 1.5.0 or higher. Shins versions track Slate version numbers.
- Clone the git repository, or
npm install [-g] widdershins, oryarn 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]
-d, --discovery Include schema.org WebAPI discovery data [boolean]
-i, --includes List of files to include, comma separated [string]
-l, --lang Automatically generate list of languages for code samples
[boolean]
-o, --outfile File to write output markdown to [string]
-r, --raw Output raw schemas not example values [boolean]
-s, --search Whether to enable search, defaults to true [boolean]
-t, --theme Syntax-highlighter theme to use [string]
-u, --user_templates directory to load override templates from [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.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 = [];
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.
Note that the list of included files is simply passed into the header of the markdown file, they are actually included by Slate or the alternative you use.
To see the list of highlight-js syntax highlighting themes, click here.
Schema.org WebAPI discovery data is included if the option above is set. See the W3C WebAPI Discovery Community Group for more information.
Templates are compiled with doT.js.
Templates have access to a data object with a range of properties based on the document context.
If you specify an options.templateCallback function, it will be called before and after each template, with three parameters, the template name, the stage, ('pre' or 'post') and the current data object. You can mutate the data object in any way you see fit, as long as you return it. Content in the data.append property will be appended to the current output stream.
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)consumes[]- an array of MIME-types the operation consumesproduces[]- an array of MIME-types the operation producesoperation- the current operation objectoperationId- the current operation idtags[]- the full list of tags applying to the operationsecurity- the security definitions applying to the operationresource- the current tag/path objectparameters[]- an array of parameters for the operation (see below)queryString- an example queryString, urlEncodedrequiredQueryString- an example queryString forrequired:trueparametersqueryParameters[]- a subset ofparametersthat arein:queryrequiredParameters[]- a subset ofqueryParametersthat arerequired:trueheaderParameters[]- a subset ofparametersthat arein:headerallHeaders[]- a concatenation ofheaderParametersand pseudo-parametersAcceptandContent-Type
parameters[]- an array of parameters, including the following pseudo-propertiesshortDesc- a truncated version of the parameter descriptionsafeType- a computed version of the parameter type, including Body and schema namesoriginalType- the original type of the parameterexampleValues- an object containing examples for use in code-templatesjson- example values in JSON compatible syntaxobject- example values in raw object form (unquoted strings etc)
enums[]- an array of (parameter)name/value pairs
responses[]- an array of responses, includingstatusandmeaningproperties
authenticationStr- a simple string of methods (and scopes where appropriate)securityDefinitions[]- an array of applicable securityDefinitions
openapi- the top-level OpenApi / Swagger documentheader- the front-matter of the Slate/Shins markdown documenthost- the (computed) host of the APIprotocol- the default/first protocol of the APIbaseUrl- the (computed) baseUrl of the API (including protocol and host)
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
Blog posting by the author of Widdershins
Thanks to @latgeek for the logo
Please feel free to add a link to your API documentation here