mermade / widdershins Goto Github PK

View Code? Open in Web Editor NEW

1.5K 16.0 319.0 1.7 MB

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown

Home Page: https://mermade.github.io/reslate

License: MIT License

JavaScript 99.94% Shell 0.06%

openapi swagger slate api documentation asyncapi semoasa openapi3

widdershins's Introduction

widdershins

OpenAPI / Swagger / AsyncAPI / Semoasa definition to Slate / ReSlate compatible markdown

Widdershins adverb:

In a direction contrary to the sun's course;
anticlockwise;
helping you produce static documentation from your OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0 definition

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
- Numerous bug fixes
As of v3.0.0 Widdershins no longer expands the definition of OpenAPI body parameters / requestBodies by default, unless they have an inline schema. You can restore the old behaviour by using the --expandBody option.
You may limit the depth of schema examples using the --maxDepth option. The default is 10.
To omit schemas entirely, please copy and customise the main.dot template.
As of v3.1.0 Widdershins includes a generated Authorization header in OpenAPI code samples. If you wish to omit this, see here.

To install

Clone the git repository, and npm i to install dependencies, or
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, ReSlate, Shins (deprecated) or html suitable for use with ReSpec.

If you need to create your input API definition, this list of available editors may be useful.

More in-depth documentation is available here.

Examples

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

Options

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 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.
--shallowSchemas	options.shallowSchemas	`boolean`	`false`	When referring to a schema with a $ref, don't show the full contents of the schema.
N/A	options.source	`string`	None	The absolute location or URL of the source file to use as the base to resolve relative references ($refs) from; required if options.resolve is set to true. For CLI commands, Widdershins uses the input file as the base for the $refs.
--summary	options.tocSummary	`boolean`	`false`	Use the operation summary as the TOC entry instead of the ID.
--useBodyName	options.useBodyName	`boolean`	Use original param name for OpenAPI 2.0 body parameter.
-v, --verbose	options.verbose	`boolean`	`false`	Increase verbosity.
-h, --help	options.help	`boolean`	`false`	Show help.
--version	options.version	`boolean`	`false`	Show version number.
-c, --code	options.codeSamples	`boolean`	`false`	Omit generated code samples.
--httpsnippet	options.httpsnippet	`boolean`	`false`	Use httpsnippet to generate code samples.
-d, --discovery	options.discovery	`boolean`	`false`	Include schema.org WebAPI discovery data.
-e, --environment	N/A	`string`	None	File to load config options from.
-i, --includes	options.includes	`string`	None	List of files to put in the `include` header of the output Markdown. Processors such as Shins can then import the contents of these files.
-l, --lang	options.lang	`boolean`	`false`	Generate the list of languages for code samples based on the languages used in the source file's `x-code-samples` examples.
--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	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`		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).

In Node.JS code, create an options object and pass it to the Widdershins convert function, as in this example:

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

To only include a subset of the pre-defined language-tabs, or to rename their display-names, you can override the options.language_tabs:

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:

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

You can also use the environment file to group OAS/Swagger tagged paths together to create a more elegant table of contents, and overall page structure.

If you need to support a version of Slate <v1.5.0 (or a renderer which also doesn't support display-names for language-tabs, such as node-slate, slate-node or whiteboard), you can use the --environment option with the included whiteboard_env.json file to simply achieve this.

If you are using the httpsnippet option to generate code samples, you can specify the client library used to perform the requests for each language by overriding the options.language_clients:

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.

The 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.

Schema.org WebAPI discovery data is included if the discovery option above is set true. See the W3C WebAPI Discovery Community Group for more information.

Language tabs

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.

Templates

By default, Widdershins uses the templates in its templates/ folder to generate the Markdown output. To customize the templates, copy some or all of them to a folder and pass their location to the user_templates parameter.

The templates include .dot templates and .def partials. To override a .dot template, you must copy it and the child .def partials that the template references. Similarly, to override a .def partial, you must also copy the parent .dot template. For OpenAPI 3, the primary template is main.dot and its main child partials are parameters.def, responses.def, and callbacks.def.

This means that it is usually easiest to copy all .dot and .def files to your user templates directory so you don't skip a template or partial. To bring in changes from Widdershins updates, you can use a visual diff tool which can run across two directories, such as Meld or WinMerge.

Template syntax

Templates are compiled with doT.js.

Templates have access to a data object with a range of properties based on the document context. For information about the parameters, see the README file for the appropriate templates:

To print the value of a parameter or variable in a template, use the code {{=parameterName}}. For example, to print the title of an OpenAPI 3 spec (from its info.title field), use the code {{=data.api.info.title}}.

To loop through values in an array, use the code {{~ arrayName :tempVariable}} to start the loop and the code {{~}} to close the loop. For example, the OpenAPI 3 partial parameters.def uses this code to create a table of the parameters in an operation:

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

For if/then logic, use the code {{? booleanExpression}} to start the code block and the code {{?}} to close the block. For example, the OpenAPI 3 main.dot template calls the security.def partial to show information about the security schemes if the OpenAPI spec includes a securitySchemes section:

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

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:

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

{{=message}}

Template callbacks

The templateCallback parameter points to a function that Widdershins calls before and after each template runs. The callback function receives a data object that contains the spec that Widdershins is processing; the function must return this object. You can use callback functions only if you are calling Widdershins from JavaScript code, not from the command line.

Widdershins passes these variables to the callback function:

templateName: The name of the template, such as main.
stage: Whether Widdershins is calling the callback function before (pre) or after (post) the template.
data: An object that contains the data that Widdershins is processing. You can mutate the data object in any way you see fit, but the function must return it whether it changes it or not. Content that you put in the data.append property is appended to the current output stream.

For example, this JavaScript code prints the name of the template and the processing stage in the output Markdown:

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

Tests

To run a test-suite:

node testRunner {path-to-APIs}

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

Comparison between this and other OpenAPI / Swagger to Slate tools

Blog posting by the author of Widdershins.

Acknowledgements

@latgeek for the logo.
@vfernandestoptal for the httpsnippet support.

Widdershins in the wild

Please feel free to add a link to your API documentation here.

Widdershins and ReSlate

Widdershins works well with Slate, but for a solely Node.js-based experience, why not try the ReSlate port?

widdershins's People

Contributors

Stargazers

Watchers

Forkers

nsundbaum pjolz jonasmunck rdsteiner nielsclay laureboyer northmccormick petdoan matejc ramxpa iqxcorp preciselyalyss hauk lcamilo15 joeflateau rbarilani carlittle gtallen1187 moerin palanik senid231 wy-z tomitakussaari mikenholt mdraoof alphagov lafcolits mrshawn191 nickrmc83 glock18 jantoniucci dbarr modio acandidmind sp-7indigo irri paybygroup dt3310321 debbabi tedepstein harrisonjorritsma bjabu nbreide ischeinkman luigi-riefolo aarzoo-bhatia didimitrie vmlf01 maxwellw indietyp supersonicclay vrialland ivan-simbirsoft lukel99 the-dan dapepe bkuhl ibrahimtareq zoues brandonvfx alexstojda nmargaritis bitwise-invest stownsend2121 pmackay andrewscea danielgtaylor joshrodstein tuanng-cognite jmather timothymcmackin jdmurphy allenhoem hardenize matt-lam bitsuisse khorevaa axelthat diegobz apatil01 evermarkets hstockersoi easysolutionsio kimwandev zmoki kempsted unboundsecurity erikaya tobiaswk bobics buka102 jobrad oliwheeler mike-zipit amughni mfranceschi6 jeetiss duc-11421 tkuldeep cdifulvio

widdershins's Issues

openapi3; finish support for callbacks

See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#callbackObject

The work to extract processOperation() has been done. Just required is to make the pathItem more like a resource used elsewhere, and to output an enclosing <div></div> with a configurable class name so renderers (like shins) can put a box or 'well' around the callback to distinguish it from the containing operation.

Security Definition other than api_key is not getting parsed

I am using token based authentication for my APIs. So in Swagger definition, I give both basic auth and api_key as security definition. But in Slate markdown only api_key is getting added leaving behind basic method. My swagger JSON includes both the security definition perfectly.

swagger_doc.json

.... "securityDefinitions":{ "basic": { "type":"basic", "description":"Access Token corresponding to the Client needs to be obtained before accessing any authenticated routes", "in":"header", "name":"basic" }, "api_key": { "type":"apiKey", "in":"header", "name":"api_key" } }, "host":"http://example.com", ...

Slate Markdown Snippet

I could not figure out how to include other ways of authentication defined in OpenAPI Specification.

Community question: does anyone use the callbacks feature?

Thinking of dropping it in the upcoming v3.0 beta. With the reworked template-first approach, I think they're no longer really necessary. Calls to a helper callback can always be added to custom templates.

Semoasa support

https://github.com/RepreZen/SEMOASA

This will be a good test of using a pre-processor, utility functions and templates only to generate the output, no hard-coding; which is the planned way-forward for the rewrites of asyncapi and openapi3 support.

reference in parameters is not compiled to md at all.

I have the following json file downloaded from swagger online editor:

{
    "swagger": "2.0",
    "info": {
        "title": "Livechat API",
        "description": "description",
        "version": "1.0.0"
    },
    "host": "example.com",
    "schemes": [
        "https"
    ],
    "basePath": "/examplewebhook/",
    "produces": [
        "application/json"
    ],
    "consumes": [
        "application/x-www-form-urlencoded"
    ],
    "paths": {
        "/receive": {
            "post": {
                "summary": "Accept incoming webhook event",
                "description": "This endpoint is being triggered every time someone replies in custom livechat software",
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/Request"
                        }
                    },
                 ],
                "tags": [
                    "Livechat"
                ],
                "responses": {
                    "200": {
                        "description": "An array of kb records",
                        "schema": {
                            "$ref": "#/definitions/Success"
                        }
                    },
                    "400": {
                        "description": "Validation errors",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "Message":{
          "type":"object",
          "required":["date","responder","messageText"],
          "properties":{
              "date" : {
              "type" : "string",
              "description": "Date of the message"
            },
             "responder" : {
              "type" : "string",
              "description": "Responder of the message. The type of user who created a message. ROBOT or USER"
            },
             "messageText" : {
              "type" : "string",
              "description": "Text of the message"
            },
          }
        },
        "Request":{
          "required":["sessionId","token","type"],
          "properties":{
            "sessionId" : {
              "type" : "string",
              "description": "ID of the session to send message to"
            },
            "token":{
               "description": "desc",
               "type": "string"
            },
            "type":{
              "description": "Type of the livechat event. May be MESSAGE,ANNOUNCE_ENTER, ANNOUNCE_EXIT",
              "type": "string"
            },
            "jsonLog":{
              "type":"object",
              "description":"Interaction log of the session, this object will be triggered on enter event and will be empty on exit or message event",
              "properties":{
                "sessionId":{
                  "type":"string",
                  "description":"ID of the current livechat session"
                },
                "integrationId":{
                  "type":"string",
                  "description":"ID of the integration"
                },
                "email":{
                  "type":"string",
                  "description":"email that associated with the current session"
                },
                "userAgent":{
                  "type":"string",
                  "description":"User agent of the client, associated with the session. Not applicable for Facebook integration"
                },
                "ipAddress":{
                  "type":"string",
                  "description": "IP address of the client, associated with the session. Not applicable for Facebook integration"
                },
                "messages":{
                  "type":"array",
                  "description":"Message logs",
                  "items":{
                    "$ref": "#/definitions/Message"
                  }
                }
              }
            }
          }
        },
        "Error": {
            "type": "object",
            "properties": {
                "success": {
                    "type": "boolean"
                },
                "error": {
                    "type": "string"
                }
            }
        },
        "Success": {
            "type": "object",
            "properties": {
                "success": {
                    "type": "boolean"
                }
            }
        }
    }
}

And I run the following command:

widdershins webhook.html -o webhook.html.md

But, there's absolutely no reference to
'Request' definition or any other definition, except those in responses. Why? I mean in md file. When I compile it to slate and html I get no any reference to POST data that should be sent to webhook. I don't understand why. Please help asap. Thanks

Regards

Details about how to customize language tabs in command line

Hi Mike,
I just read all the issues and the readme.md in project and tried for several times to get a customize language tabs using command line. I tried to use -e option like widdershins -e config.json test.json -o test.md .
And in config json, I used json format option content like options.language_tabs = [{ 'http': 'HTTP' }, { 'javascript': 'JavaScript' }, { 'javascript--nodejs': 'Node.JS' }, { 'python': 'Python' }, { 'ruby': 'Ruby' }]; or "options.language_tabs" = [ { "http": "HTTP" }, { "javascript": "JavaScript" }, { "javascript--nodejs": "Node.JS" }, { "python": "Python" }, { "ruby": "Ruby" }];
However, it just didn't work. Thus I wandering how should I write the config file to achieve this goal. If you can give a more specific sample for this, that would be very helpful.
Again, thanks for your hard-working on this project! It really helps a lot.

Is it possible to fetch json file from server instead of disk?

Hi,

Is it possible to fetch json file from server instead of disk?

I would like to run something like

node widdershins http://localhost:8080/test/v2/api-docs -o index.html.md markdown

AsyncAPI support

In progress, see the two_oh branch.

During conversion, should ignore comments in YAML files

If there are any hash symbols (pound symbols) used to denote comments in a YAML file, this reads those and the conversion to Markdown is totally broken.

To recreate, just add a comment at the very first line of your YAML and then convert the file to Markdown.

[Question] Replace Method Name from swagger operationId to summary.

Hello,

I use widdershins to transform a swagger model to a slate compliant markdown files.
We discover that the swagger operationId (like addPet, deletePet...) is used to create the method name (in the left menu & middle page).

We would prefer to use swagger summary (Add a new Pet, Delete a Pet) field for this purpose.

Is there a simple way to achieve this goal ? (By coding or by passing a specific parameter)

Thanks in advance.

PS: Thanks also for the current work.

Allow to pass an array instead of single apiObj for microservices

A new parameter 'body' gets added for hash type params

Specs

Swagger 2.0
Widdershins installation from the branch v3.0

I am using parameters of type hash for our APIs. Swagger generates the JSON as given below

"paths":{"/betaweb/users/sign_in":{"post":{"description":"User Authentication API","produces":["application/json"],"consumes":["application/json"],"parameters":[{"in":"formData","name":"user[email]","description":"User email","type":"string","required":false},{"in":"formData","name":"user[username]","type":"string","required":false},{"in":"formData","name":"user[password]","description":"User Password","type":"string","required":true}],"responses":{"201":{"description":"Created"},"422":{"description":"Invalid Login Credentials"}},"tags":["users"],"operationId":"User Authentication API"}},

But my Slate Markdown adds a parameter body to my request as below.

I couldn't figure out to remove the body parameter.

And also, the password parameter required is set to true in the Swagger JSON. But the in the documentation, required field for password is set to false

Change default number of example languages

Hi,

First of all, thanks for this very nice framework! It is a perfect fit in our API doc pipeline.

I've been playing around with limiting the number of languages show in the languages tabs, by using configuration similar to the following:

options.language_tabs = [{'shell': 'Shell'},{'http': 'HTTP'}];

This hides other languages in the top tab menu, but the code samples for those other languages are still showing in the right column, which makes that entire column look very strange. Am I doing something wrong or is this an issue with the framework? If needed, I'd be happy to provide a pull request.

Also, would be interested to hear about any plans for future features/improvements that you might have for this framework.

openapi3; support for links

see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#linkObject

Improve code samples with httpsnippet?

See closed PR #18 - and https://github.com/glennjones/swagger-har for converting to HAR format or https://github.com/ErikWittern/swagger-snippet for direct swagger-to-httpsnippet (though these are for OpenAPI v2.0 only).

No newline after title in index.md breaks language samples tabs.

Hi Mike,

I hope this is not just a configuration issue on my part, so a pre-apology from me if I just PEBKAC'd.

I've been working on a small project to automate the conversion of Swagger JSON to Slate documentation, and I'm using Widdershins to convert the JSON to markdown. This then gets converted to Slate markup using this node module:

https://github.com/jmanek/slate_node

I'm using:

Node v6.9.5
NPM 4.3.0.

To generate the JSON, I'm using the following plugin in Eclipse:

https://github.com/kongchen/swagger-maven-plugin

This produces this JSON output:

{
  "swagger" : "2.0",
  "info" : {
    "description" : "This is a description",
    "version" : "1.1.1.1",
    "title" : "This is a title",
    "license" : {
      "name" : "Apache 2.0",
      "url" : "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host" : "http://somesite.com:8080",
  "tags" : [ {
    "name" : "service"
  } ],
  "schemes" : [ "http", "https" ],
  "paths" : {
    "/something/list" : {
      "get" : {
        "tags" : [ "service" ],
        "summary" : "Some random summary.",
        "description" : "Some random description.",
        "operationId" : "list",
        "produces" : [ "application/json" ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/SomeObject"
            }
          },
          "500" : {
            "description" : "Unable to fetch list."
          }
        },
        "security" : [ {
          "api_key" : [ ]
        }, {
          "media_auth" : [ "read:something", "write:something" ]
        } ]
      }
    }
  },
  "definitions" : {
    "SomeObject" : {
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "integer",
          "format" : "int32"
        },
        "name" : {
          "type" : "string"
        },
        "layout" : {
          "type" : "string"
        }
      }
    }
  }
}

I then convert the testoutput.json file to markdown using Widdershins, with the following command:

node/node node_modules/widdershins/widdershins /var/tmp/testoutput.json -o /var/tmp/index.md

This produces the index.md file attached.

When I view the markup produced by Slate Node, the language samples tabs aren't shown. Example here:

However, if I edit the index.md and add a newline after the title, the language tabs get shown.

E.g(broken).

---
title: This is a title v1.1.1.1
language_tabs:
  - shell: Shell
  - http: HTTP
  - html: JavaScript
  - javascript: Node.JS
  - python: Python
  - ruby: Ruby
  - java: Java
toc_footers: []
includes: []
search: true
highlight_theme: darkula
---

to(fixed):

---
title: This is a title v1.1.1.1

language_tabs:
  - shell: Shell
  - http: HTTP
  - html: JavaScript
  - javascript: Node.JS
  - python: Python
  - ruby: Ruby
  - java: Java
toc_footers: []
includes: []
search: true
highlight_theme: darkula
---

Generating the Slate markup from the altered index.md with the newline after the title generates the language tabs as expected. Example here:

I've debugged into Slate Node and if I console.log the token(line 66) in marked.js I get the following output when I generate the markup without the newline in the index.md:

{ type: 'paragraph',
  text: 'title: This is a title v1.1.1.1\nlanguage_tabs:' }
{ type: 'list_start', ordered: false }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'text', text: 'includes: []' }
{ type: 'text', text: 'search: true' }
{ type: 'text', text: 'highlight_theme: darkula' }
{ type: 'list_item_end' }
{ type: 'list_end' }

When I generate it with the newline in the index.md it gives me the well formed data, which fixes the language tabs not showing. Here it is properly generated:

{ type: 'paragraph', text: 'title: This is a title v1.1.1.1' }
{ type: 'paragraph', text: 'language_tabs:' }
{ type: 'list_start', ordered: false }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'list_item_start' }
{ type: 'text', text: 'includes: []' }
{ type: 'text', text: 'search: true' }
{ type: 'text', text: 'highlight_theme: darkula' }
{ type: 'list_item_end' }
{ type: 'list_end' }

I think this might be a bug, but if I'm wrong please feel free to close the issue. Thanks for a great plugin! :)

Kind regards,
Eoghan

An in-range update of swagger2openapi is breaking the build 🚨

Version 2.6.1 of swagger2openapi just got published.

Branch	Build failing 🚨
Dependency	swagger2openapi
Current Version	2.6.0
Type	dependency

This version is covered by your current version range and after updating it in your project the build failed.

swagger2openapi is a direct dependency of this project this is very likely breaking your project right now. If other packages depend on you it’s very likely also breaking them.
I recommend you give this issue a very high priority. I’m sure you can resolve this 💪

Status Details

❌ continuous-integration/travis-ci/push The Travis CI build could not complete due to an error Details

Not sure how things should work exactly?

There is a collection of frequently asked questions and of course you may always ask my humans.

Your Greenkeeper Bot 🌴

An in-range update of js-yaml is breaking the build 🚨

Version 3.9.0 of js-yaml just got published.

Branch	Build failing 🚨
Dependency	js-yaml
Current Version	3.8.4
Type	dependency

This version is covered by your current version range and after updating it in your project the build failed.

js-yaml is a direct dependency of this project this is very likely breaking your project right now. If other packages depend on you it’s very likely also breaking them.
I recommend you give this issue a very high priority. I’m sure you can resolve this 💪

Status Details

❌ continuous-integration/travis-ci/push The Travis CI build failed Details

Commits

The new version differs by 9 commits.

d411edd 3.9.0 released
1b45ecc Browser files rebuild
561891c eslint & CS update
d87c338 Deps bump
8249dea Update changelog
2cd3b01 add missed test files
b76645e Travis: add node.js v8
3c148e2 Support loadAll/safeLoadAdd without iterator (return array), #350
bd32506 Add condenseFlow option, close #346

See the full diff

Not sure how things should work exactly?

There is a collection of frequently asked questions and of course you may always ask my humans.

Your Greenkeeper Bot 🌴

Allow to pass an array instead of single apiObj for microservices

Instead of passing an apiObj, we could pass an array of apiObj to convert into a markdown with nested fields (h1, h2, h3) for microservices

How can I specify languages for code examples?

Hi.
Is there any option to specify languages for code examples to my desire?
It is possible to choose them all or nothing. But some configuration file or cli option will be helpful.

Listing more than one body parameter.

Apologies if this is not a widdershins issue but I am not 100% sure. I am trying to parse my swagger .json file to slate mark up and I can never get more than one body parameter to show in the parameters list for an endpoint. I understand the a request can only have one body but I want to list multiple params and simply have "In Body" next to it. However if I have more than one body param in my swagger.json and I run widdershins to convert it crashes.

I can make a single body param and reference it to an object but then the params show under "Body example" on the right hand slide of the slate doc and it only shows "body" under params on the left which I feel is a bit confusing. I could obviously just hard code the parameter details in but really trying to avoid that option.

This is my desired output:

But this is all I can do (one body param or widdershins fails to parse):

Feel free to close if this is something outside of Widdershins control.

Include security details for AsyncAPI

Much of the data preparation code and the templates can probably be taken from the openapi3 renderer.

See https://github.com/asyncapi/asyncapi/blob/develop/README.md#securitySchemeObject
See also docgen example http://editor.asyncapi.org/

Keep minimum/maximum fields in generated docs

Input:

{
  "swagger" : "2.0",
  "info" : {
    "description" : "This is documentation of the My API",
    "version" : "0.1",
    "title" : "My API"
  },
  "host" : "api.myurl.com",
  "tags" : [ {
    "name" : "Something",
    "description" : "Endpoint for managing something"
  } ],
  "schemes" : [ "https" ],
  "paths" : {
    "api/somethings" : {
      "get" : {
        "tags" : [ "Something" ],
        "summary" : "getSomething",
        "description" : "Fetch a list of somethings",
        "operationId" : "getSomething",
        "consumes" : [ "application/json" ],
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "limit",
          "in" : "query",
          "description" : "Limit the number of results",
          "required" : false,
          "type" : "integer",
          "default" : 25,
          "maximum" : 10000.0,
          "minimum" : 1.0,
          "format" : "int32"
        }, ],
        "responses" : {
          "200" : {
            "description" : "successful operation"
          }
        }
      }
    }
  },
  "definitions" : {}
}

Output of widdershins swagger.json -o index.html.md:

---
title: My API v0.1
language_tabs:
  - shell: Shell
  - http: HTTP
  - javascript: JavaScript
  - javascript--nodejs: Node.JS
  - ruby: Ruby
  - python: Python
  - java: Java
toc_footers: []
includes: []
search: true
highlight_theme: darkula
---

# My API v0.1

> Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

This is documentation of the My API

Base URLs:

* <a href="https://api.myurl.com/">https://api.myurl.com/</a>







# Something

Endpoint for managing something

## getSomething

> Code samples

/```shell
# You can also use wget
curl -X GET https://api.myurl.com/api/somethings

/```

/```http
GET https://api.myurl.com/api/somethings HTTP/1.1
Host: api.myurl.com



/```

/```javascript

$.ajax({
  url: 'https://api.myurl.com/api/somethings',
  method: 'get',


  success: function(data) {
    console.log(JSON.stringify(data));
  }
})
/```

/```javascript--nodejs
const request = require('node-fetch');


fetch('https://api.myurl.com/api/somethings',
{
  method: 'GET'


})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});
/```

/```ruby
require 'rest-client'
require 'json'



result = RestClient.get 'https://api.myurl.com/api/somethings',
  params: {
  }

p JSON.parse(result)
/```

/```python
import requests

r = requests.get('https://api.myurl.com/api/somethings', params={

)

print r.json()
/```

/```java
URL obj = new URL("https://api.myurl.com/api/somethings");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());
/```

`GET api/somethings`

*getSomething*

Fetch a list of somethings

### Parameters

Parameter|In|Type|Required|Description
---|---|---|---|---|
limit|query|integer(int32)|false|Limit the number of results



### Responses

Status|Meaning|Description|Schema
---|---|---|---|
200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|successful operation|None

<aside class="success">
This operation does not require authentication
</aside>

The output is missing information about the allowable range of the limit parameter. Is there a way to include that information in the generated docs?

Bug with how multiple references to the same schema object are processed

I've noticed that if, in the Swagger spec definitions section, I define an object which defines the same $ref for more than one property then only the first of these properties gets rendered to markdown, e.g.

definitions:
  NewThing:
    type: object
    required:
      - origin
      - destination
    properties:
      origin:
        $ref: '#/definitions/LatLong'
      destination:
        $ref: '#/definitions/LatLong'

Only origin appears correctly in the markdown and there is no trace of destination (LatLong is defined further down the swagger file).

Regards... Steve

`env: node\r: No such file or directory` on macos

Trying to use widdershins on macos I get a env: node\r: No such file or directory error. I got around it by installing dos2unix (using brew) and then executing dos2unix /usr/local/lib/node_modules/widdershins/widdershins.js. Should this be a problem, or was there something specific to my system that required me to change the line endings?

Improve AsyncAPI code samples

E.g. from new AsyncAPI code-generator examples, or examples of other Async library calls.

[Questions] OpenAPI - Parameters & Schemas sections

Aloah,

I currently tweak my OpenAPi/slate integration with widdershins and I encounter a special use case.
By using default command like
widdershins --summary -y apiName.yaml index.html.md

I have this result where FormRequest (Body Parameter of my Method) is present with the schema associated inside the Parameters section (See also the >> character associated). Notice there's also a Schemas section in my main menu.

When I use the same command line with --noschema parameter like
widdershins --summary --noschema -y apiName.yaml index.html.md

I obtain this result. The parameters section only contains the FormRequest body parameter.
Schemas section in my main menu is also not present. It makes the hyperlink to FormRequest impossible to use.

My question is simple.

Is it possible to have the Schemas sections available
AND
not displaying the inline Parameters ( >> parameters) ?

I would prefer my user to click the FormRequest hyperlink to have access directly to the parameter schema instead of having it displaying inside the parameters section with the >> symbol.

Thanks in advance.

openapi3; use embedded examples in place of sampled schemas where present

See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#exampleObject

Add logo

Anything considered - for example a clock face with arrows going anti-clockwise with {A} in the centre.

Create in a docs/ directory.

How to add java language option to show methods?

Java is missing in the languages option.. Where to add a language?

Definition and schema references are not generated in slate documentation

{
  "swagger" : "2.0",
  "info" : {
    "description" : "Provider Service API",
    "version" : "1.0.0",
    "title" : "provider-service-api",
    "termsOfService" : "http://pro.com/info/terms",
    "contact" : {
      "name" : "Pro.com",
      "url" : "http://pro.com",
      "email" : "[email protected]"
    },
    "license" : {
      "name" : "Apache 2.0",
      "url" : "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host" : "api.pro.com",
  "basePath" : "/provider-service",
  "tags" : [ {
    "name" : "provider"
  } ],
  "schemes" : [ "http" ],
  "paths" : {
    "/providers" : {
      "post" : {
        "tags" : [ "provider" ],
        "summary" : "Add a provider",
        "description" : "",
        "operationId" : "addProvider",
        "consumes" : [ "application/json" ],
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "in" : "body",
          "name" : "body",
          "required" : false,
          "schema" : {
            "$ref" : "#/definitions/Provider"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/Provider"
            }
          }
        }
      }
    },
    "/providers/{id}" : {
      "get" : {
        "tags" : [ "provider" ],
        "summary" : "Get a provider given a id",
        "description" : "",
        "operationId" : "getProvider",
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/Provider"
            }
          },
          "404" : {
            "description" : "Provider not found"
          }
        }
      },
      "put" : {
        "tags" : [ "provider" ],
        "summary" : "Update a provider",
        "description" : "",
        "operationId" : "updateProvider",
        "consumes" : [ "application/json" ],
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "required" : true,
          "type" : "string"
        }, {
          "in" : "body",
          "name" : "body",
          "required" : false,
          "schema" : {
            "$ref" : "#/definitions/Provider"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/Provider"
            }
          }
        }
      },
      "delete" : {
        "tags" : [ "provider" ],
        "summary" : "Delete a given provider",
        "description" : "",
        "operationId" : "deleteProvider",
        "consumes" : [ "application/json" ],
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "required" : true,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/Provider"
            }
          }
        }
      }
    }
  },
  "definitions" : {
    "Provider" : {
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "string",
          "description" : "provider id"
        },
        "name" : {
          "type" : "string",
          "description" : "provider name"
        },
        "displayName" : {
          "type" : "string",
          "description" : "provider display name"
        }
      },
      "description" : "A service provider"
    }
  }
}

The definition of provider and the individual attributes description are not copied over to the documentation even though they are present in swagger.json. Can you please help me understand how the schema definitions and the attributes definition could be brought out in slate documentation?

Thanks

Does 'AllOf' criteria is Considered?

Because when I give any json with allOf criteria desired output is not coming..

Allow templateCallbacks to provide additional content (data.append)

The callback would add it in a property of the data object (data.append), which would be appended to the main output, and then deleted.

This would allow an empty template with a callback function to act as a code-generator etc.

No binary created when installed via npm or yarn

I tried installing both via npm and yarn, but neither install produced a runnable widdershins binary that I could run

RangeError when using widdershins with a new OpenApi v3 spec file

➜  api git:(swagger2) ✗ widdershins openapi.0.3.json
Compiling all doT templates...
Compiling authentication.dot to function
Compiling authentication_none.dot to function
Compiling code_http.dot to function
Compiling code_java.dot to function
Compiling code_javascript.dot to function
Compiling code_nodejs.dot to function
Compiling code_python.dot to function
Compiling code_ruby.dot to function
Compiling code_shell.dot to function
Compiling discovery.dot to function
Compiling footer.dot to function
Compiling heading_body_parameter.dot to function
Compiling heading_code_samples.dot to function
Compiling heading_example_responses.dot to function
Compiling heading_main.dot to function
Compiling parameters.dot to function
Compiling response_headers.dot to function
Compiling response_schema.dot to function
Compiling responses.dot to function
Compiling schema_header.dot to function
Compiling schema_properties.dot to function
Compiling schema_sample.dot to function
Compiling security.dot to function
/usr/local/lib/node_modules/widdershins/openapi3.js:761
            content += templates.schema_sample(data) + '\n';
                                                     ^

RangeError: Invalid string length
    at Object.convert (/usr/local/lib/node_modules/widdershins/openapi3.js:761:54)
    at Object.convert (/usr/local/lib/node_modules/widdershins/index.js:18:18)
    at Object.<anonymous> (/usr/local/lib/node_modules/widdershins/widdershins.js:101:11)
    at Module._compile (module.js:624:30)
    at Object.Module._extensions..js (module.js:635:10)
    at Module.load (module.js:545:32)
    at tryModuleLoad (module.js:508:12)
    at Function.Module._load (module.js:500:3)
    at Function.Module.runMain (module.js:665:10)
    at startup (bootstrap_node.js:187:16)

Is there something wrong with my openapi.json file? I'll attach it here: openapi.0.3.json.zip

Missing example response

Input swagger.json:

{
  "swagger" : "2.0",
  "info" : {
    "description" : "This is documentation of my API",
    "version" : "0.3",
    "title" : "My API"
  },
  "host" : "my.url.com",
  "tags" : [ {
    "name" : "Somethings",
    "description" : "Endpoint for managing somethings"
  } ],
  "schemes" : [ "https" ],
  "paths" : {
    "/api/somethings" : {
      "get" : {
        "tags" : [ "Events" ],
        "summary" : "getSomethings",
        "description" : "Get list of somethings matching query",
        "operationId" : "getSomethings",
        "consumes" : [ "application/json" ],
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "type",
          "in" : "query",
          "description" : "Type of something",
          "required" : false,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/EventResponse"
            }
          }
        },
        "security" : [ {
          "session" : [ ]
        }, {
          "api_key" : [ ]
        } ]
      }
    }
  },
  "securityDefinitions" : { },
  "definitions" : {
    "Event" : {
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "integer",
          "format" : "int64",
          "description" : "ID given by the API to the event."
        },
        "additionalData" : {
          "description" : "Customizable extra data about the event",
          "$ref" : "#/definitions/JsonElement"
        }
      },
      "description" : "An event represents something."
    },
    "EventResponse" : {
      "type" : "object",
      "properties" : {
        "data" : {
          "$ref" : "#/definitions/List_Event"
        }
      }
    },
    "JsonArray" : {
      "type" : "object",
      "properties" : {
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "JsonElement" : {
      "type" : "object",
      "properties" : {
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "JsonNull" : {
      "type" : "object",
      "properties" : {
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "JsonObject" : {
      "type" : "object",
      "properties" : {
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "JsonPrimitive" : {
      "type" : "object",
      "properties" : {
        "boolean" : {
          "type" : "boolean",
          "default" : false
        },
        "number" : {
          "type" : "boolean",
          "default" : false
        },
        "string" : {
          "type" : "boolean",
          "default" : false
        },
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "List_Event" : {
      "type" : "object",
      "properties" : {
        "items" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/Event"
          }
        }
      }
    }
  }
}

Output of widdershins swagger.json -o index.html.md:

---
title: My API v0.3
language_tabs:
  - shell: Shell
  - http: HTTP
  - javascript: JavaScript
  - javascript--nodejs: Node.JS
  - ruby: Ruby
  - python: Python
  - java: Java
toc_footers: []
includes: []
search: true
highlight_theme: darkula
---

# My API v0.3

> Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

This is documentation of my API

Base URLs:

* <a href="https://my.url.com/">https://my.url.com/</a>





# Events

## getSomethings

> Code samples

/```shell
# You can also use wget
curl -X GET https://my.url.com//api/somethings \
  -H 'Accept: application/json'

/```

/```http
GET https://my.url.com//api/somethings HTTP/1.1
Host: my.url.com

Accept: application/json

/```

/```javascript
var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://my.url.com//api/somethings',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})
/```

/```javascript--nodejs
const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://my.url.com//api/somethings',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});
/```

/```ruby
require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://my.url.com//api/somethings',
  params: {
  }, headers: headers

p JSON.parse(result)
/```

/```python
import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://my.url.com//api/somethings', params={

}, headers = headers)

print r.json()
/```

/```java
URL obj = new URL("https://my.url.com//api/somethings");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());
/```

`GET /api/somethings`

*getSomethings*

Get list of somethings matching query

### Parameters

Parameter|In|Type|Required|Description
---|---|---|---|---|
type|query|string|false|Type of something


> Example responses

/```json
{
  "data": {}
}
/```
### Responses

Status|Meaning|Description|Schema
---|---|---|---|
200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|successful operation|[EventResponse](#schemaeventresponse)

<aside class="warning">
To perform this operation, you must be authenticated by means of one of the following methods:
None, None
</aside>

# Schemas

## Event

<a name="schemaevent"></a>

/```json
{
  "id": 0,
  "additionalData": {}
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
id|integer(int64)|false|ID given by the API to the event.
additionalData|[JsonElement](#schemajsonelement)|false|No description



## EventResponse

<a name="schemaeventresponse"></a>

/```json
{
  "data": {}
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
data|[List_Event](#schemalist_event)|false|No description



## JsonArray

<a name="schemajsonarray"></a>

/```json
{
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonArray": false,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonArray|boolean|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
jsonObject|boolean|false|No description



## JsonElement

<a name="schemajsonelement"></a>

/```json
{
  "jsonArray": false,
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
jsonArray|boolean|false|No description
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonObject|boolean|false|No description



## JsonNull

<a name="schemajsonnull"></a>

/```json
{
  "jsonArray": false,
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
jsonArray|boolean|false|No description
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonObject|boolean|false|No description



## JsonObject

<a name="schemajsonobject"></a>

/```json
{
  "jsonArray": false,
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
jsonArray|boolean|false|No description
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonObject|boolean|false|No description



## JsonPrimitive

<a name="schemajsonprimitive"></a>

/```json
{
  "boolean": false,
  "number": false,
  "string": false,
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonArray": false,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
boolean|boolean|false|No description
number|boolean|false|No description
string|boolean|false|No description
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonArray|boolean|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
jsonObject|boolean|false|No description



## List_Event

<a name="schemalist_event"></a>

/```json
{
  "items": [
    {}
  ]
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
type|Unknown|false|No description
items|[Event](#schemaevent)|false|No description
x-isArray|Unknown|false|No description
$ref|Unknown|false|No description

What I expect to see is a response body, not a data field with an empty object. Is there are problem when widdershins is parsing JsonElement that causes everything else in my Event class to disappear? Because even though I add other fields they don't appear unless I remove the JsonElement field.

How do I make the Code Samples visible ?

I see [object Object] [ object Object] where I should see the name of a language on the top right. How do I make the language tab show the languages ? I am using petstore.json. I am trying to view the markdown in Whiteboard.

Add details of the schema and property descriptions - with links

Detailed Description

Currently the documents are generated without the details of the resource, attributes and it would be great to include the resource detail along with individual attributes details in the documentation so that the consumer of API have sufficient details. There could be a attribute which just accepts enumerated values and it is currently not possible to list them.
Eg. To add a provider the parameter just describes type as Provider as shown below.

Expected Behavior

Depending on complexity it would be great if we could support one of these features. A model section which lists all the resources, attributes and any description and rules like how swagger2slate generates.

Or a even better is to the way Stripe does by listing the resource and attributes details along with detail description.

List instead of table helps in rendering nested objects in much nicer way.

Parameter passing broken

My API spec is written in YAML. I have been unable to get the following to work:

widdershins -y docs/openapi.yml docs/compiled.md

It fails saying that it can't find the file -y.

Digging a bit deeper, it looks like parameter passing has been broken since 2.2.4. Version 2.2.3 works as intended

Shared parameters are dereferenced too late for use in code sample templates

As noticed by ~~@bc-alyssNoland~~ @PreciselyAlyss
https://github.com/MikeRalphson/bigcommerce-api/blob/openapi/swagger/v3-api.yaml

oneOf etc

Currently schemas marked up with oneOf or anyOf often display nothing at all. Would it be possible to (maybe) define some levels at which this is considered appropriate, and display blocks with '-or-' or similar between them? I understand that clarity may require only supporting "normal" or "obvious" uses of this!

Adding discriminator support would be wonderful. Adding it as a dropdown or similar would be completely above and beyond expectations, but completely awesome.

Add data.queryString and data.requiredQueryString

For code samples where the query parameters need to be assembled into the path. Depends on #10

Promise support

Using call-me-maybe

Offer a "direct model only" option

I have a fairly convoluted model I'm trying to convey using api-schema. I don't want to exclude the model from the generated documentation, but it would be fantastic to only show elements that were directly referenced from the operations (with their referenced elements inline as they are).

I have an awful lot of reuse, and one-of-many sections, and displaying that "internal" implementation muddles up the schema display a lot.

Option to inline the externalDocs URLs

May need two switches for main (info) level externalDocs and for the ones at operation level.

Add parameter.exampleValues property

Convert parameter definition into a schema and use openapi-sampler again to derive example values.

Avoid double-slash between host url and path?

Input:

{
  "swagger" : "2.0",
  "info" : {
    "description" : "This is documentation of the My API",
    "version" : "0.1",
    "title" : "My API"
  },
  "host" : "api.myurl.com",
  "tags" : [ {
    "name" : "Something",
    "description" : "Endpoint for managing something"
  } ],
  "schemes" : [ "https" ],
  "paths" : {
    "/api/somethings" : {
      "get" : {
        "tags" : [ "Something" ],
        "summary" : "getSomething",
        "description" : "Fetch a list of somethings",
        "operationId" : "getSomething",
        "consumes" : [ "application/json" ],
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "limit",
          "in" : "query",
          "description" : "Limit the number of results",
          "required" : false,
          "type" : "integer",
          "default" : 25,
          "maximum" : 10000.0,
          "minimum" : 1.0,
          "format" : "int32"
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation"
          }
        }
      }
    }
  },
  "definitions" : {}
}

Output curl example:

/```shell
# You can also use wget
curl -X GET https://api.myurl.com//api/somethings
/```

Is there an easy way for me to avoid the double slash after .com there? (Other than perhaps sed 's|.com//|.com/|g':)

Mistake in openapi3/schema_properties.dot?

Hi
In the Properties section of schema_properties.dot the table doesn't get generated correctly 'cos the 2nd row has too many columns (5 instead of 4):

Name|Type|Required|Description
---|---|---|---|---|

Easy enough to override this template with a user one that corrects this, but thought you'd like to know for your next release.

cheers.... Steve

TypeError using [email protected]

Hey Mike, is there something wrong with my openapi.json file here?
openapi.json.zip

➜  api git:(swagger2) ✗ widdershins --version
3.0.0-beta0.1
➜  api git:(swagger2) ✗ widdershins -x swagger/openapi.json --maxDepth 5 -o index.html.md
Compiling all doT templates...
Loaded def authentication.def
Loaded def authentication_none.def
Loaded def callbacks.def
Loaded def debug.def
Loaded def discovery.def
Loaded def footer.def
Loaded def links.def
Loaded def parameters.def
Loaded def responses.def
Loaded def security.def
Compiling code_http.dot to function
Compiling code_java.dot to function
Compiling code_javascript.dot to function
Compiling code_nodejs.dot to function
Compiling code_python.dot to function
Compiling code_ruby.dot to function
Compiling code_shell.dot to function
Compiling main.dot to function
Compiling operation.dot to function
Compiling translations.dot to function
TypeError: Cannot read property 'trim' of undefined
    at Object.getResponses (/usr/local/lib/node_modules/widdershins/openapix.js:324:46)
    at Object.eval [as operation] (eval at doT.template (/usr/local/lib/node_modules/widdershins/node_modules/dot/doT.js:133:11), <anonymous>:3:2566)
    at Object.eval [as main] (eval at doT.template (/usr/local/lib/node_modules/widdershins/node_modules/dot/doT.js:133:11), <anonymous>:3:3445)
    at convertInner (/usr/local/lib/node_modules/widdershins/openapix.js:536:30)
    at Object.convert (/usr/local/lib/node_modules/widdershins/openapix.js:557:9)
    at Object.convert (/usr/local/lib/node_modules/widdershins/index.js:22:22)
    at doit (/usr/local/lib/node_modules/widdershins/widdershins.js:86:15)
    at Object.<anonymous> (/usr/local/lib/node_modules/widdershins/widdershins.js:144:5)
    at Module._compile (module.js:624:30)
    at Object.Module._extensions..js (module.js:635:10)

OpenAPI 3.0.x support

In progress, see the two_oh branch, where all Swagger 2.0 definitions are handled by first converting them to OpenAPI 3.0.0

mermade / widdershins Goto Github PK

widdershins's Introduction

widdershins

Widdershins adverb:

News

To install

Getting started

Examples

Options

Language tabs

Templates

Template syntax

Template callbacks

Tests

Comparison between this and other OpenAPI / Swagger to Slate tools

Acknowledgements

Widdershins in the wild

Widdershins and ReSlate

widdershins's People

Contributors

Stargazers

Watchers

Forkers

widdershins's Issues

swagger_doc.json

Slate Markdown Snippet

Version 2.6.1 of swagger2openapi just got published.

Version 3.9.0 of js-yaml just got published.

Detailed Description

Expected Behavior

Recommend Projects

Recommend Topics

Recommend Org