### Custom Parameter Table Template Example

Source: https://context7.com/mermade/widdershins/llms.txt

Example of a doT.js template for rendering parameter tables, demonstrating iteration over parameters and accessing their properties.

```javascript
// Custom parameter table template example (parameters.def)
// Template variables available:
// - data.parameters[] - array of parameter objects
// - p.name - parameter name
// - p.in - parameter location (query, header, path, cookie)
// - p.safeType - computed parameter type
// - p.required - boolean required flag
// - p.shortDesc - truncated description

// doT.js template syntax example:
`
|Name|In|Type|Required|Description|
|---|---|---|---|---|
{{~ data.parameters :p}}
|{{=p.name}}|{{=p.in}}|{{=p.safeType}}|{{=p.required}}|{{=p.shortDesc || 'none'}}| 
{{~}}
`
```

--------------------------------

### Install Widdershins Globally

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicCLI.md

Install Widdershins globally using NPM to enable command-line usage from any directory. This is a prerequisite for using the CLI.

```shell
npm install -g widdershins
```

--------------------------------

### Install Widdershins via npm

Source: https://context7.com/mermade/widdershins/llms.txt

Install the package globally or as a local project dependency.

```bash
npm install -g widdershins
```

```bash
npm install --save widdershins
```

--------------------------------

### Configure Language Tabs in Environment File

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicCLI.md

Define language tabs for code examples in an environment file using JSON format. This allows Widdershins to generate examples in specified languages like Python and Ruby.

```json
{
"language_tabs": [{ "python": "Python" }, { "ruby": "Ruby" }]
}
```

--------------------------------

### Complete JavaScript Program for Markdown Conversion

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicJS.md

This is a complete example of a JavaScript program that imports Widdershins, configures options, reads a Swagger file, converts it to Markdown, and writes the output to a file.

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

--------------------------------

### Install Widdershins as a Project Dependency

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicJS.md

Add Widdershins to your project's dependencies using npm. This command installs the package and saves it to your package.json file.

```shell
npm install --save widdershins
```

--------------------------------

### Generate ReSpec Documentation

Source: https://context7.com/mermade/widdershins/llms.txt

Create a ReSpec configuration file and use the CLI to generate HTML output.

```bash
cat > respec-config.json << 'EOF'
{
  "specStatus": "ED",
  "editors": [{
    "name": "API Team",
    "company": "Example Corp"
  }],
  "github": "https://github.com/example/api-spec",
  "shortName": "example-api"
}
EOF

# Generate ReSpec HTML output
widdershins --respec respec-config.json api.json -o api-spec.html
```

--------------------------------

### Copy and Use Custom Templates

Source: https://context7.com/mermade/widdershins/llms.txt

Customize API documentation by copying default templates to a user directory and then specifying this directory with the --user_templates flag.

```bash
# Copy templates for customization
mkdir -p ./my_templates
cp -r node_modules/widdershins/templates/openapi3/* ./my_templates/

# Use custom templates
widdershins --user_templates ./my_templates api.json -o api.md
```

--------------------------------

### Run Widdershins with Environment File

Source: https://context7.com/mermade/widdershins/llms.txt

Execute Widdershins using an environment file for conversion settings.

```bash
# Use environment file for conversion
widdershins --environment config.json petstore.json -o petstore.md
```

--------------------------------

### Run Test Suite

Source: https://github.com/mermade/widdershins/blob/main/README.md

Execute the test runner against a directory of API definition files.

```bash
node testRunner {path-to-APIs}
```

--------------------------------

### Convert AsyncAPI Specifications

Source: https://context7.com/mermade/widdershins/llms.txt

Generate documentation from AsyncAPI 1.x specifications, supporting topics, messages, and payload schemas. Requires the 'yaml' package.

```javascript
const widdershins = require('widdershins');
const fs = require('fs');
const yaml = require('yaml');

// Load AsyncAPI specification
const asyncApiSpec = yaml.parse(fs.readFileSync('asyncapi.yaml', 'utf8'));

const options = {
  codeSamples: true,
  language_tabs: [
    { 'javascript': 'JavaScript' },
    { 'python': 'Python' },
    { 'go': 'Go' }
  ],
  sample: true,
  maxDepth: 10
};

widdershins.convert(asyncApiSpec, options)
  .then(markdown => {
    fs.writeFileSync('asyncapi-docs.md', markdown, 'utf8');
    console.log('AsyncAPI documentation generated');
  })
  .catch(err => console.error(err));
```

--------------------------------

### Include External Files

Source: https://context7.com/mermade/widdershins/llms.txt

Inject custom Markdown files into the generated documentation output.

```bash
# Add include files
widdershins --includes "errors.md,changelog.md,support.md" api.json -o api.md
```

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

const options = {
  includes: ['errors.md', 'changelog.md', 'authentication.md'],
  toc_footers: {
    'https://example.com/signup': 'Sign Up for API Key',
    'https://github.com/example/api': 'GitHub Repository'
  }
};

const apiSpec = JSON.parse(fs.readFileSync('api.json', 'utf8'));

widdershins.convert(apiSpec, options)
  .then(markdown => {
    fs.writeFileSync('api-docs.md', markdown, 'utf8');
  })
  .catch(err => console.error(err));
```

--------------------------------

### Convert API definitions using the CLI

Source: https://context7.com/mermade/widdershins/llms.txt

Execute conversion tasks from the command line with various flags to control input sources, output formats, and generation settings.

```bash
# Basic conversion from JSON file
widdershins petstore.json -o petstore.md

# Convert from URL
widdershins https://petstore.swagger.io/v2/swagger.json -o petstore.md

# Convert YAML file with specific language tabs
widdershins --language_tabs 'ruby:Ruby' 'python:Python' 'javascript:JavaScript' api.yaml -o api.md

# Disable search and use operation summary in TOC
widdershins --search false --summary defs/petstore3.json -o petstore3.md

# Generate docs with httpsnippet code samples
widdershins --httpsnippet --language_tabs 'shell:cURL:curl' 'node:Node.js:request' api.json -o api.md

# Omit auto-generated code samples
widdershins --code api.json -o api.md

# Output raw schemas instead of example values
widdershins --raw api.json -o api.md

# Expand inline request body schemas
widdershins --expandBody api.json -o api.md

# Resolve external $refs in the specification
widdershins --resolve api.json -o api.md

# Output HTML directly instead of Markdown
widdershins --html api.json -o api.html
```

--------------------------------

### Configure Widdershins Options

Source: https://github.com/mermade/widdershins/blob/main/README.md

Set various options for the Widdershins converter, such as theme, search, and template callbacks. The `loadedFrom` option is only needed if the input document does not specify a host.

```javascript
//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);
});
```

--------------------------------

### Generate Markdown Documentation

Source: https://github.com/mermade/widdershins/blob/main/README.md

Use this command to convert an OpenAPI 3.0 definition file to markdown. It specifies language tabs for code samples and a summary of definitions. The output is saved to a markdown file.

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

--------------------------------

### Run JavaScript Conversion Script

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicJS.md

Execute your JavaScript program from the command line using Node.js to perform the OpenAPI/Swagger to Markdown conversion.

```shell
node convertMarkdown.js
```

--------------------------------

### Print Template Variables

Source: https://github.com/mermade/widdershins/blob/main/README.md

Use double curly braces with an equals sign to output data properties.

```text
{{=parameterName}}
```

```text
{{=data.api.info.title}}
```

--------------------------------

### Configure Widdershins with Environment File

Source: https://context7.com/mermade/widdershins/llms.txt

Use a JSON or YAML environment file to set reusable conversion options like language tabs and tag groups.

```json
{
  "language_tabs": [
    { "http": "HTTP" },
    { "javascript": "JavaScript" },
    { "javascript--nodejs": "Node.JS" },
    { "python": "Python" },
    { "ruby": "Ruby" },
    { "go": "Go" }
  ],
  "language_clients": [
    { "shell": "curl" },
    { "node": "request" },
    { "java": "unirest" }
  ],
  "tagGroups": [
    {
      "title": "Pet Operations",
      "description": "Manage pets in the store",
      "tags": ["pet"]
    },
    {
      "title": "Store Operations",
      "description": "Access store orders",
      "tags": ["store"]
    },
    {
      "title": "User Management",
      "description": "User account operations",
      "tags": ["user"]
    }
  ],
  "tocSummary": true,
  "headings": 3,
  "verbose": true
}
```

--------------------------------

### Configure Widdershins in Node.js

Source: https://github.com/mermade/widdershins/blob/main/README.md

Initialize an options object and pass it to the Widdershins convert function to customize output behavior.

```javascript
const converter = require('widdershins');
let options = {}; // defaults shown
options.codeSamples = true;
options.httpsnippet = false;
//options.language_tabs = [];
//options.language_clients = [];
```

--------------------------------

### Set Custom API Key Value

Source: https://context7.com/mermade/widdershins/llms.txt

Define a custom API key placeholder for generated code samples via CLI or programmatic options.

```bash
# Use custom API key in code samples
widdershins --customApiKeyValue "your-api-key-here" api.json -o api.md
```

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

const options = {
  customApiKeyValue: 'sk_live_example_key_12345',
  codeSamples: true,
  language_tabs: [{ 'shell': 'cURL' }, { 'javascript': 'JavaScript' }]
};

const apiSpec = JSON.parse(fs.readFileSync('api.json', 'utf8'));

widdershins.convert(apiSpec, options)
  .then(markdown => {
    fs.writeFileSync('api-docs.md', markdown, 'utf8');
  })
  .catch(err => console.error(err));
```

--------------------------------

### Customize schema output in templates

Source: https://github.com/mermade/widdershins/wiki/faq

Modify the main.dot template to include schema patterns in the generated documentation tables.

```diff
diff --git a/templates/openapi3/main.dot b/templates/openapi3/main.dot
index 3547fb7..241aed5 100644
--- a/templates/openapi3/main.dot
+++ b/templates/openapi3/main.dot
@@ -104,8 +104,8 @@ Base URLs:
 {{?}}
 
 {{? block.rows.length}}|Name|Type|Required|Restrictions|Description|
-|---|---|---|---|---|{{?}}
-{{~ block.rows :p}}|{{=p.displayName}}|{{=p.safeType}}|{{=p.required}}|{{=p.restrictions||'none'}}|{{=p.description||'none'}}|
+|---|---|---|---|---|---|{{?}}
+{{~ block.rows :p}}|{{=p.displayName}}|{{=p.safeType}}|{{=p.required}}|{{=p.restrictions||'none'}}|{{=p.description||'none'}}|{{=p.schema.pattern||'no pattern'}}
 {{~}}
 {{~}}
 {{? (blocks[0].rows.length === 0) && (blocks.length === 1) }}
```

--------------------------------

### Specify Client Libraries for Code Samples

Source: https://github.com/mermade/widdershins/blob/main/README.md

Override `options.language_clients` to specify the client library used for generating code samples with the `httpsnippet` option. This allows you to control which libraries are used for each language.

```javascript
options.language_clients = [{ 'shell': 'curl' }, { 'node': 'request' }, { 'java': 'unirest' }];
```

--------------------------------

### Configure Widdershins with Environment File

Source: https://github.com/mermade/widdershins/blob/main/README.md

Use the `--environment` option to specify a JSON or YAML-formatted `options` object. This can be used to configure language tabs, verbose logging, and tag groups for organizing API paths.

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

--------------------------------

### Generate HTTP Snippets

Source: https://context7.com/mermade/widdershins/llms.txt

Configure Widdershins to generate language-specific HTTP client code samples.

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

const apiSpec = JSON.parse(fs.readFileSync('api.json', 'utf8'));

const options = {
  httpsnippet: true,
  language_tabs: [
    { 'shell': 'cURL' },
    { 'javascript--fetch': 'JavaScript (Fetch)' },
    { 'node': 'Node.js' },
    { 'python': 'Python' },
    { 'java': 'Java' },
    { 'php': 'PHP' }
  ],
  language_clients: [
    { 'shell': 'curl' },
    { 'javascript--fetch': 'fetch' },
    { 'node': 'request' },
    { 'python': 'requests' },
    { 'java': 'unirest' },
    { 'php': 'curl' }
  ],
  experimental: true  // Enable multipart media type support
};

widdershins.convert(apiSpec, options)
  .then(markdown => {
    fs.writeFileSync('api-docs.md', markdown, 'utf8');
  })
  .catch(err => console.error(err));
```

--------------------------------

### Configure Widdershins Options

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicJS.md

Define an options object to customize the conversion process. Use the JavaScript parameter names as specified in the Widdershins README.

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

--------------------------------

### Convert OpenAPI File with Environment File

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicCLI.md

Convert an OpenAPI or Swagger file to Markdown using the Widdershins CLI. This command specifies an environment file for options, the input OpenAPI file, and the output Markdown file.

```shell
widdershins --environment env.json swagger.json -o myOutput.md
```

--------------------------------

### Write Markdown Output to File

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicJS.md

After the conversion is complete, write the generated Markdown content to a file using Node.js's `fs.writeFileSync` function.

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

--------------------------------

### Execute Arbitrary JavaScript

Source: https://github.com/mermade/widdershins/blob/main/README.md

Insert JavaScript code blocks within curly braces to define variables or perform logic.

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

{{=message}}
```

--------------------------------

### Loop Through Arrays

Source: https://github.com/mermade/widdershins/blob/main/README.md

Use the tilde syntax to iterate over arrays within a template.

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

--------------------------------

### Convert API Blueprint Specifications

Source: https://context7.com/mermade/widdershins/llms.txt

Convert API Blueprint format specifications by passing the raw string content directly to the Widdershins convert function.

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

// Load API Blueprint as raw string (not parsed)
const apiBlueprintContent = fs.readFileSync('api.apib', 'utf8');

const options = {
  codeSamples: true,
  language_tabs: [
    { 'shell': 'cURL' },
    { 'javascript': 'JavaScript' }
  ]
};

// Pass string directly for API Blueprint format
widdershins.convert(apiBlueprintContent, options)
  .then(markdown => {
    fs.writeFileSync('api-blueprint-docs.md', markdown, 'utf8');
  })
  .catch(err => console.error(err));
```

--------------------------------

### Implement Template Callback

Source: https://github.com/mermade/widdershins/blob/main/README.md

Define a callback function to mutate data or append content during the conversion process.

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

--------------------------------

### Convert API definitions using the Node.js library

Source: https://context7.com/mermade/widdershins/llms.txt

Use the convert function to transform an API specification object into Markdown, providing an options object to customize the output.

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

// Load and parse an OpenAPI 3.0 specification
const apiSpec = JSON.parse(fs.readFileSync('petstore.json', 'utf8'));

const options = {
  codeSamples: true,            // Generate code samples
  language_tabs: [              // Languages for code samples
    { 'shell': 'cURL' },
    { 'javascript': 'JavaScript' },
    { 'python': 'Python' },
    { 'ruby': 'Ruby' }
  ],
  theme: 'darkula',             // Syntax highlighting theme
  search: true,                 // Enable search in output
  sample: true,                 // Show example values (not raw schemas)
  tocSummary: true,             // Use operation summary in TOC
  headings: 2,                  // Heading levels in TOC
  maxDepth: 10,                 // Max depth for schema examples
  expandBody: false,            // Expand referenced request bodies
  shallowSchemas: false,        // Show full schema contents
  resolve: false,               // Resolve external $refs
  discovery: false,             // Include schema.org WebAPI data
  yaml: false,                  // Display schemas in YAML format
  omitBody: false,              // Omit body param from table
  omitHeader: false             // Omit YAML front-matter
};

widdershins.convert(apiSpec, options)
  .then(markdown => {
    fs.writeFileSync('api-docs.md', markdown, 'utf8');
    console.log('Documentation generated successfully');
  })
  .catch(err => {
    console.error('Conversion failed:', err.message);
  });
```

--------------------------------

### Customize Language Tabs

Source: https://github.com/mermade/widdershins/blob/main/README.md

Override the default `options.language_tabs` to include a subset of pre-defined language tabs or rename their display names. This is useful for controlling which code samples are shown.

```javascript
options.language_tabs = [{ 'go': 'Go' }, { 'http': 'HTTP' }, { 'javascript': 'JavaScript' }, { 'javascript--node': 'Node.JS' }, { 'python': 'Python' }, { 'ruby': 'Ruby' }];
```

--------------------------------

### Convert OpenAPI/Swagger to Markdown

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicJS.md

Utilize the `widdershins.convert` function to transform the parsed API definition into Markdown. This function returns a Promise that resolves with the Markdown output.

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

--------------------------------

### Implement Template Callback Function

Source: https://context7.com/mermade/widdershins/llms.txt

Define a callback function to modify data or append content before and after template rendering. Ensure the data object is always returned.

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

function templateCallback(templateName, stage, data) {
  // Log template processing for debugging
  console.log(`Processing template: ${templateName} (${stage})`);

  // Modify data before 'main' template
  if (templateName === 'main' && stage === 'pre') {
    // Add custom header content
    data.append = '> **Note:** This API is in beta.\n\n';
  }

  // Append content after 'operation' template
  if (templateName === 'operation' && stage === 'post') {
    data.append = '\n---\n';
  }

  // Must return the data object
  return data;
}

const apiSpec = JSON.parse(fs.readFileSync('api.json', 'utf8'));

const options = {
  templateCallback: templateCallback,
  codeSamples: true,
  language_tabs: [{ 'javascript': 'JavaScript' }]
};

widdershins.convert(apiSpec, options)
  .then(markdown => {
    fs.writeFileSync('api-docs.md', markdown, 'utf8');
  })
  .catch(err => console.error(err));
```

--------------------------------

### Conditional Logic

Source: https://github.com/mermade/widdershins/blob/main/README.md

Use question mark syntax to wrap blocks of code in conditional statements.

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

--------------------------------

### Read and Parse OpenAPI/Swagger File

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicJS.md

Use Node.js built-in modules to read the content of an OpenAPI or Swagger file and parse it into a JavaScript object.

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

--------------------------------

### Programmatic ReSpec Conversion

Source: https://context7.com/mermade/widdershins/llms.txt

Use the Widdershins Node.js API to convert an OpenAPI spec to ReSpec-formatted HTML.

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

const apiSpec = JSON.parse(fs.readFileSync('api.json', 'utf8'));

const options = {
  html: true,
  omitHeader: true,
  respec: {
    specStatus: 'ED',
    editors: [{ name: 'API Team', company: 'Example Corp' }],
    github: 'https://github.com/example/api-spec',
    shortName: 'example-api'
  },
  abstract: './include/abstract.md',
  sotd: './include/sotd.md'
};

widdershins.convert(apiSpec, options)
  .then(html => {
    fs.writeFileSync('api-spec.html', html, 'utf8');
  })
  .catch(err => console.error(err));
```

--------------------------------

### Import Widdershins in JavaScript

Source: https://github.com/mermade/widdershins/blob/main/docs/ConvertingFilesBasicJS.md

Import the Widdershins module into your JavaScript file to make its functions available for use in your program.

```javascript
const widdershins = require('widdershins');
```

--------------------------------

### Resolve External References

Source: https://context7.com/mermade/widdershins/llms.txt

Enable resolution of external $ref pointers in API specifications.

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

const apiSpec = JSON.parse(fs.readFileSync('api.json', 'utf8'));

const options = {
  resolve: true,
  // source must be absolute path or URL for resolving relative $refs
  source: process.cwd() + '/api.json',
  codeSamples: true,
  language_tabs: [{ 'javascript': 'JavaScript' }]
};

widdershins.convert(apiSpec, options)
  .then(markdown => {
    fs.writeFileSync('api-docs.md', markdown, 'utf8');
  })
  .catch(err => console.error(err));
```

```bash
# CLI automatically uses input file as source for resolving
widdershins --resolve api.json -o api.md
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.