[pull] master from Mermade:master

.eslintrc.json

@@ -3,6 +3,9 @@
         "es6": true,
         "node": true
     },
+    "parserOptions": {
+        "ecmaVersion": 2017
+    },
     "extends": "eslint:recommended",
     "rules": {
         "accessor-pairs": "error",
@@ -77,7 +80,7 @@
         "init-declarations": "off",
         "jsx-quotes": "error",
         "key-spacing": "off",
-        "keyword-spacing": "off",
+        "keyword-spacing": "error",
         "line-comment-position": "off",
         "linebreak-style": [
             "error",
@@ -180,7 +183,7 @@
         "no-throw-literal": "error",
         "no-trailing-spaces": "error",
         "no-undef-init": "error",
-        "no-undefined": "warn",
+        "no-undefined": "off",
         "no-underscore-dangle": "off",
         "no-unmodified-loop-condition": "error",
         "no-unneeded-ternary": [

.gitignore

@@ -1,16 +1,19 @@
 *.html.md
+foo.md
 user_templates/
 *.tgz
 *.old
 in/
 out/
+dev/
 scripts/
 utils/
 
 # Logs
 logs
 *.log
 npm-debug.log*
+report.????????.??????.??????.?.???.json
 
 # Runtime data
 pids

.travis.yml

@@ -2,7 +2,7 @@ language: node_js
 node_js:
   - "node"
   - "lts/*"
-  - "8"
+  - "10"
 install:
   - npm i
 before_script:
@@ -13,11 +13,12 @@ before_script:
   - . ./bin/setflags.sh
   - mkdir -p out
 script:
+  - npm run lint
   - npm test
   - node widdershins -o out/petstore.md defs/petstore3.json
   - node node_modules/mdv/mdv out/petstore.md
   - node $nflags testRunner openapi-directory/APIs/
   - node $nflags testRunner openapi-definitions/
-  - node $nflags testRunner openapi3-examples/pass/
+  - node $nflags testRunner openapi3-examples/3.0/pass/
   - node $nflags testRunner --resolve defs/
 #  - node testRunner hapi/APIs/

README.md

@@ -1,6 +1,6 @@
 # widdershins
-OpenAPI / Swagger / AsyncAPI / Semoasa definition to [Slate](https://github.com/lord/slate) /
-[Shins](https://github.com/mermade/shins) compatible markdown
+OpenAPI / Swagger / AsyncAPI / Semoasa definition to [Slate](https://github.com/slatedocs/slate) /
+[ReSlate](https://github.com/mermade/reslate) compatible markdown
 
 ![Build](https://img.shields.io/travis/Mermade/widdershins/master.svg) [![Tested on APIs.guru](https://api.apis.guru/badges/tested_on.svg)](https://APIs.guru) [![Tested on Mermade OpenAPIs](https://img.shields.io/badge/Additional%20Specs-419-brightgreen.svg)](https://github.com/mermade/OpenAPI_specifications)
 [![Known Vulnerabilities](https://snyk.io/test/npm/widdershins/badge.svg)](https://snyk.io/test/npm/widdershins)
@@ -17,6 +17,7 @@ OpenAPI / Swagger / AsyncAPI / Semoasa definition to [Slate](https://github.com/
 ### News
 
 * Version 4.0 changes:
+  * Now uses Promises not callbacks
   * Option to output html directly, and to ReSpec format
   * Unified JavaScript and Node.js code-samples, PHP added
   * `restrictions` column (`readOnly`/`writeOnly`) added to schema templates
@@ -29,11 +30,11 @@ OpenAPI / Swagger / AsyncAPI / Semoasa definition to [Slate](https://github.com/
 ### To install
 
 * Clone the git repository, and `npm i` to install dependencies, or
-* `npm install [-g] widdershins` to install globally
+* `npm install -g widdershins` to install globally
 
 ### Getting started
 
-Widdershins is generally used as a stage in an API documentation pipeline. The pipeline begins with an API definition in OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI or Semoasa format. Widdershins converts this description into markdown suitable for use by a **renderer**, such as [Slate](https://github.com/lord/slate), [Shins](https://github.com/mermade/shins) or html suitable for use with [ReSpec](https://github.com/w3c/respec).
+Widdershins is generally used as a stage in an API documentation pipeline. The pipeline begins with an API definition in OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI or Semoasa format. Widdershins converts this description into markdown suitable for use by a **renderer**, such as [Slate](https://github.com/slatedocs/slate), [ReSlate](https://github.com/mermade/reslate), [Shins](https://github.com/mermade/shins)  (*deprecated*) or html suitable for use with [ReSpec](https://github.com/w3c/respec).
 
 If you need to create your input API definition, [this list of available editors](https://apis.guru/awesome-openapi3/category.html#editors) may be useful.
 
@@ -49,9 +50,10 @@ node widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --su
 
 | CLI parameter name | JavaScript parameter name | Type | Default value | Description |
 | --- | --- | --- | --- | --- |
+| --clipboard | options.clipboard | `boolean` | `true` | Sets the value of the `code_clipboard` property in the heading, so that markdown processors can include clipboard support. |
 | --customApiKeyValue | options.customApiKeyValue | `string` | `ApiKey` | Set a custom API key value to use as the API key in generated code examples. |
 | --expandBody | options.expandBody | `boolean` | `false` | If a method's requestBody parameter refers to a schema by reference (not with a inline schema), by default, Widdershins shows only a reference to this parameter. Set this option to true to expand the schema and show all properties in the request body. |
-| --headings | options.headings | `integer` | 2 | Set the value of the `headingLevel` parameter in the header so Shins knows how many heading levels to show in the table of contents. Currently supported only by Shins, not by Slate, which lacks this feature. |
+| --headings | options.headings | `integer` | 2 | Set the value of the `headingLevel` parameter in the header so markdown processors know how many heading levels to show in the table of contents. Currently supported only by Shins, not by Slate, which lacks this feature. |
 | --omitBody | options.omitBody | `boolean` | `false` | By default, Widdershins includes the body parameter as a row in the parameters table before the rows that represent the fields in the body. Set this parameter to omit that body parameter row. |
 | --omitHeader | options.omitHeader | `boolean` | `false` | Omit the header / YAML front-matter in the generated Markdown file. |
 | --resolve | options.resolve | `boolean` | `false` | Resolve external $refs, using the `source` parameter or the input file as the base location. |
@@ -71,11 +73,11 @@ node widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --su
 | --language_tabs | options.language_tabs | `string` | (Differs for each input type) | List of language tabs for code samples using language[:label[:client]] format, such as `javascript:JavaScript:request`. |
 | -m, --maxDepth | options.maxDepth | `integer` | 10 | Maximum depth to show for schema examples. |
 | -o, --outfile | N/A | `string` | None | File to write the output markdown to. If left blank, Widdershins sends the output to stdout. |
-| -r, --raw | options.raw | `boolean` | `false` | Output raw schemas instead of example values. |
-| -s, --search | options.search | `boolean` | `true` | Set the value of the `search` parameter in the header so Markdown processors like Shins include search or not in their output. |
+| -r, --raw | **inverse** of options.sample | `boolean` | `false` | Output raw schemas instead of example values. |
+| -s, --search | options.search | `boolean` | `true` | Set the value of the `search` parameter in the header so Markdown processors like Slate include search or not in their output. |
 | -t, --theme | options.theme | `string` | darkula | Syntax-highlighter theme to use. |
 | -u, --user_templates | options.user_templates | `string` | None | Directory to load override templates from. |
-| -x, --experimental | options.experimental | `boolean` |  | For backwards compatibility only; ignored. |
+| -x, --experimental | options.experimental | `boolean` |  | Use httpSnippet for multipart mediatypes. |
 | -y, --yaml | options.yaml | `boolean` | `false` | Display JSON schemas in YAML format. |
 |  | options.templateCallback | `function` | None | A `function` that is called before and after each template (JavaScript code only). |
 |  | options.toc_footers | `object` | A map of `url`s and `description`s to be added to the ToC footers array (JavaScript code only). |
@@ -103,22 +105,26 @@ 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,function(err,str){
+converter.convert(apiObj,options)
+.then(str => {
   // str contains the converted markdown
+})
+.catch(err => {
+  console.error(err);
 });
 ```
 
 To only include a subset of the pre-defined language-tabs, or to rename their display-names, you can override the `options.language_tabs`:
 
 ```javascript
-options.language_tabs = [{ 'go': 'Go' }, { 'http': 'HTTP' }, { 'javascript': 'JavaScript' }, { 'javascript--nodejs': 'Node.JS' }, { 'python': 'Python' }, { 'ruby': 'Ruby' }];
+options.language_tabs = [{ 'go': 'Go' }, { 'http': 'HTTP' }, { 'javascript': 'JavaScript' }, { 'javascript--node': 'Node.JS' }, { 'python': 'Python' }, { 'ruby': 'Ruby' }];
 ```
 
 The `--environment` option specifies a JSON or YAML-formatted `options` object, for example:
 
 ```json
 {
-  "language_tabs": [{ "go": "Go" }, { "http": "HTTP" }, { "javascript": "JavaScript" }, { "javascript--nodejs": "Node.JS" }, { "python": "Python" }, { "ruby": "Ruby" }],
+  "language_tabs": [{ "go": "Go" }, { "http": "HTTP" }, { "javascript": "JavaScript" }, { "javascript--node": "Node.JS" }, { "python": "Python" }, { "ruby": "Ruby" }],
   "verbose": true,
   "tagGroups": [
     {
@@ -143,6 +149,8 @@ If you are using the `httpsnippet` option to generate code samples, you can spec
 options.language_clients = [{ 'shell': 'curl' }, { 'node': 'request' }, { 'java': 'unirest' }];
 ```
 
+If the language name differs between the markdown name required to syntax highlight and the httpsnippet required target, both can be specified in the form `markdown--target`.
+
 To see the list of languages and clients supported by httpsnippet, [click here](https://github.com/Kong/httpsnippet/tree/master/src/targets).
 
 The `loadedFrom` option is only needed where the OpenAPI / Swagger definition does not specify a host, and (as per the OpenAPI [specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields)) the API endpoint is deemed to be based on the source URL
@@ -156,7 +164,7 @@ Schema.org WebAPI discovery data is included if the `discovery` option above is
 
 Widdershins supports the `x-code-samples` [vendor-extension](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#operation-object-vendor-extensions) 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](https://github.com/mermade/shins) versions track Slate version numbers.
+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.
 
 ## Templates
 
@@ -196,7 +204,7 @@ For if/then logic, use the code `{{? booleanExpression}}` to start the code bloc
 You can run arbitrary JavaScript within a template by inserting a code block within curly braces. For example, this code creates a variable and references it with normal doT.js syntax later in the template:
 ```
 {{ {
-var message = "Hello!";
+let message = "Hello!";
 } }}
 
 {{=message}}
@@ -222,15 +230,16 @@ let options = {};
 options.templateCallback = myCallBackFunction;
 
 function myCallBackFunction(templateName, stage, data) {
-  var statusString = "Template name: " + templateName + "\n";
+  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, function(err, str) {
+converter.convert(apiObj, options)
+.then(str => {
   fs.writeFileSync('petstore3Output.md', str, 'utf8');
 });
 ```
@@ -272,7 +281,8 @@ Please feel free to add a link to your API documentation here.
 * [LeApp daemon API](https://leapp-to.github.io/shins/index.html)
 * [Shutterstock API](https://api-reference.shutterstock.com/)
 * [Shotstack Video Editing API](https://shotstack.io/docs/api/index.html)
+* [Admetricks API](http://dev.admetricks.com/)
 
-### Widdershins and Shins
+### Widdershins and ReSlate
 
-* `Widdershins` works well with Slate, but for a solely Node.js-based experience, why not try the [Shins](https://github.com/mermade/shins) port?
+* `Widdershins` works well with Slate, but for a solely Node.js-based experience, why not try the [ReSlate](https://github.com/mermade/reslate) port?

defs/asyncapi12d.yaml

@@ -114,7 +114,7 @@ components:
 
   parameters:
     streetlightId:
-      $ref: 'includes/streetlightId.yaml#/components/parameters/streetlightId'
+      #$ref: 'includes/streetlightId.yaml#/components/parameters/streetlightId'
       name: streetlightId
       description: The ID of the streetlight.
       schema:

defs/issue193.yaml

@@ -0,0 +1,27 @@
+openapi: 3.0.1
+info:
+  title: API
+  version: 1.0.0
+paths:
+  /:
+    post:
+      responses:
+        '200':
+          description: OK
+      requestBody:
+        description: A JSON object containing pet information
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - $ref: '#/components/schemas/Cat'
+                - $ref: '#/components/schemas/Dog'
+                - $ref: '#/components/schemas/Hamster'
+components:
+  schemas:
+    Cat:
+      type: object
+    Dog:
+      type: object
+    Hamster:
+      type: object

defs/issue323.json

@@ -0,0 +1,50 @@
+{
+	"swagger": "2.0",
+	"info": {
+		"version": "1.0",
+		"title": "Redacted Public API"
+	},
+	"host": "redacted-api.us-east-1.amazonaws.com",
+	"basePath": "/prd",
+	"schemes": ["https"],
+	"paths": {
+		"/{version}/{any+}": {
+			"options": {
+				"consumes": ["application/json"],
+				"responses": {
+					"200": {
+						"description": "200 response",
+						"headers": {
+							"Access-Control-Allow-Origin": {
+								"type": "string"
+							},
+							"Access-Control-Allow-Methods": {
+								"type": "string"
+							},
+							"Access-Control-Max-Age": {
+								"type": "string"
+							},
+							"Access-Control-Allow-Headers": {
+								"type": "string"
+							}
+						}
+					}
+				}
+			},
+			"x-amazon-apigateway-any-method": {
+				"consumes": ["application/json"],
+				"produces": ["application/json"],
+				"responses": {
+					"404": {
+						"description": "404 response",
+						"headers": {
+							"Access-Control-Allow-Origin": {
+								"type": "string"
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

defs/minimal.yaml

@@ -0,0 +1,10 @@
+openapi: 3.0.2
+info:
+  version: 1.0.0
+  title: API
+paths:
+  /foo:
+    get:
+      responses:
+        '200':
+          description: OK

docs/ConvertingFilesBasicCLI.md

@@ -42,4 +42,4 @@ Include the options in the command or specify the name of the environment file w
 widdershins --environment env.json swagger.json -o myOutput.md
 ```
 
-Now you can use the Markdown file in your documentation or use a tool such as Shins to convert it to HTML.
+Now you can use the Markdown file in your documentation or use a tool such as [Shins](https://github.com/Mermade/shins) to convert it to HTML.

docs/ConvertingFilesBasicJS.md

@@ -1,7 +1,7 @@
 # Converting an OpenAPI/Swagger file to Markdown with the Widdershins JavaScript interface
 
 Using Widdershins in a JavaScript program gives you control over the full range of options.
-To use Widdershins from the CIU, see [Converting an OpenAPI/Swagger file to Markdown with the Widdershins CLI](ConvertingFilesBasicCLI.md).
+To use Widdershins from the CLI, see [Converting an OpenAPI/Swagger file to Markdown with the Widdershins CLI](ConvertingFilesBasicCLI.md).
 
 ## Prerequisites
 
@@ -41,17 +41,25 @@ const fileData = fs.readFileSync('swagger.json', 'utf8');
 const swaggerFile = JSON.parse(fileData);
 ```
 1. Use Widdershins to convert the file.
-Widdershins returns the converted Markdown in a callback function:
+Widdershins returns the converted Markdown via a Promise:
 ```javascript
-widdershins.convert(swaggerFile, options, function(err, markdownOutput) {
+widdershins.convert(swaggerFile, options)
+.then(markdownOutput => {
   // markdownOutput contains the converted markdown
+})
+.catch(err => {
+  // handle errors
 });
 ```
-1. Within the callback function, write the Markdown to a file:
+1. When the Promise resolves, write the Markdown to a file:
 ```javascript
-widdershins.convert(swaggerFile, options, function(err, markdownOutput) {
+widdershins.convert(swaggerFile, options)
+.then(markdownOutput => {
   // markdownOutput contains the converted markdown
   fs.writeFileSync('myOutput.md', markdownOutput, 'utf8');
+})
+.catch(err => {
+  // handle errors
 });
 ```
 1. Run the JavaScript program:
@@ -72,10 +80,14 @@ const options = {
 const fileData = fs.readFileSync('swagger.json', 'utf8');
 const swaggerFile = JSON.parse(fileData);
 
-widdershins.convert(swaggerFile, options, function(err, markdownOutput) {
+widdershins.convert(swaggerFile, options)
+.then(markdownOutput => {
   // markdownOutput contains the converted markdown
   fs.writeFileSync('myOutput.md', markdownOutput, 'utf8');
+})
+.catch(err => {
+  // handle errors
 });
 ```
 
-Now you can use the Markdown file in your documentation or use a tool such as Shins to convert it to HTML.
+Now you can use the Markdown file in your documentation or use a tool such as [Shins](https://github.com/Mermade/shins) to convert it to HTML.