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 CLI, see Converting an OpenAPI/Swagger file to Markdown with the Widdershins CLI.

Prerequisites

• Install NodeJS and Node Package Manager (NPM). See nodejs.org.
• If you don’t already have an NPM project, run npm init from the folder in which you want to create the program. NPM walks you through the process of setting up an NPM project and creates a package.json file to store the project configuration. Most of the NPM settings are not relevant to Widdershins; the important part of the process is that it sets up a project that can install and manage NPM packages such as Widdershins so you can use those packages in your programs.
• From the root folder of your project (the folder that contains the package.json file), add Widdershins as a dependency by running this command:

  npm install --save widdershins
  

Now you can use Widdershins in JavaScript programs in the project.

Converting files with JavaScript

1. Create a JavaScript program with the following general steps. You can name the file anything you want.
2. In the JavaScript file, import Widdershins so you can use it in the program:

   const widdershins = require('widdershins');
   

3. Set up your options in an options object. Use the JavaScript parameter name from the README.md file, not the CLI parameter name. For example, these options generate code samples in Python and Ruby:

   const options = {
     language_tabs: [{ python: "Python" }, { ruby: "Ruby" }]
   };
   

4. Import and parse the OpenAPI or Swagger file. This example uses the NodeJS FileSystem and JSON packages:

   const fs = require('fs');
   const fileData = fs.readFileSync('swagger.json', 'utf8');
   const swaggerFile = JSON.parse(fileData);
   

5. Use Widdershins to convert the file. Widdershins returns the converted Markdown via a Promise:

   widdershins.convert(swaggerFile, options)
   .then(markdownOutput => {
     // markdownOutput contains the converted markdown
   })
   .catch(err => {
     // handle errors
   });
   

6. When the Promise resolves, write the Markdown to a file:

   widdershins.convert(swaggerFile, options)
   .then(markdownOutput => {
     // markdownOutput contains the converted markdown
     fs.writeFileSync('myOutput.md', markdownOutput, 'utf8');
   })
   .catch(err => {
     // handle errors
   });
   

7. Run the JavaScript program:

   node convertMarkdown.js
   

The complete JavaScript program looks like this:

const widdershins = require('widdershins');
const fs = require('fs');

const options = {
  language_tabs: [{ python: "Python" }, { ruby: "Ruby" }]
};

const fileData = fs.readFileSync('swagger.json', 'utf8');
const swaggerFile = JSON.parse(fileData);

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.