widdershins-reborn 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Original work Copyright (c) 2016 Mermade Software (Mike Ralphson)
+Fork maintained by Sikandar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# widdershins-reborn
+
+> A maintained fork of [widdershins](https://github.com/Mermade/widdershins) — designed as a **library-first** API for converting OpenAPI/Swagger/AsyncAPI definitions to Markdown or HTML.
+
+[![npm version](https://img.shields.io/npm/v/widdershins-reborn.svg)](https://www.npmjs.com/package/widdershins-reborn)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why widdershins-reborn?
+
+The original `widdershins` package was CLI-focused and unmaintained since 2020. This fork is:
+
+- **Library-first** — clean JS API, perfect for apps, build pipelines, and doc generators
+- **Actively maintained** — bug fixes, dependency updates, new features
+- **Modern Node.js** — supports Node 14.x through 22.x
+- **TypeScript-ready** — type definitions included (coming soon)
+
+## Install
+
+```bash
+npm install widdershins-reborn
+```
+
+## Quick Start (JavaScript)
+
+```javascript
+const widdershins = require('widdershins-reborn');
+const fs = require('fs');
+
+// Load your OpenAPI/Swagger/AsyncAPI definition
+const api = JSON.parse(fs.readFileSync('petstore.json', 'utf8'));
+
+// Convert to Markdown
+widdershins.convert(api, {
+  search: true,
+  sample: true,
+  language_tabs: [
+    { javascript: 'JavaScript' },
+    { python: 'Python' }
+  ]
+})
+.then(markdown => {
+  fs.writeFileSync('api-docs.md', markdown, 'utf8');
+  console.log('Documentation generated!');
+})
+.catch(err => {
+  console.error('Conversion failed:', err);
+});
+```
+
+## Quick Start (ESM / Modern Node)
+
+```javascript
+import widdershins from 'widdershins-reborn';
+import { readFileSync } from 'fs';
+
+const api = JSON.parse(readFileSync('petstore.json', 'utf8'));
+
+const markdown = await widdershins.convert(api, {
+  search: true,
+  sample: true
+});
+
+console.log(markdown);
+```
+
+## API Reference
+
+### `widdershins.convert(api, options)`
+
+Converts an API definition to Markdown. Returns a `Promise<string>`.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `api` | `object \| string` | Parsed OpenAPI/Swagger/AsyncAPI object, or a string (for API Blueprint) |
+| `options` | `object` | Conversion options (see below) |
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `search` | `boolean` | `true` | Include search in output |
+| `sample` | `boolean` | `true` | Generate example values (false = raw schemas) |
+| `codeSamples` | `boolean` | `false` | Include generated code samples |
+| `httpsnippet` | `boolean` | `false` | Use httpsnippet for code generation |
+| `language_tabs` | `array` | `[]` | Language tabs: `[{ javascript: 'JavaScript' }]` |
+| `language_clients` | `array` | `[]` | Client libraries: `[{ shell: 'curl' }]` |
+| `theme` | `string` | `'darkula'` | Syntax highlighting theme |
+| `discovery` | `boolean` | `false` | Include schema.org WebAPI discovery data |
+| `headings` | `number` | `2` | Heading depth for TOC |
+| `tocSummary` | `boolean` | `false` | Use operation summary in TOC |
+| `shallowSchemas` | `boolean` | `false` | Don't expand $ref schemas |
+| `expandBody` | `boolean` | `false` | Expand request body schemas |
+| `maxDepth` | `number` | `10` | Max depth for schema examples |
+| `yaml` | `boolean` | `false` | Display schemas in YAML format |
+| `resolve` | `boolean` | `false` | Resolve external $refs |
+| `source` | `string` | — | Base URL for resolving refs |
+| `includes` | `string[]` | `[]` | Files to include in output |
+| `user_templates` | `string` | — | Directory with custom doT.js templates |
+| `templateCallback` | `function` | — | Called before/after each template |
+| `html` | `boolean` | `false` | Output HTML instead of Markdown |
+| `respec` | `object` | — | ReSpec config object (implies html) |
+| `clipboard` | `boolean` | `true` | Include clipboard support |
+| `customApiKeyValue` | `string` | `'ApiKey'` | Custom API key for code samples |
+| `omitBody` | `boolean` | `false` | Omit body param from table |
+| `omitHeader` | `boolean` | `false` | Omit YAML front-matter |
+| `useBodyName` | `boolean` | `false` | Use original param name for OAS2 body |
+| `verbose` | `boolean` | `false` | Verbose output |
+| `experimental` | `boolean` | `false` | Use experimental features |
+| `toc_footers` | `array` | `[]` | Footer links for TOC |
+
+### Template Callback
+
+The `templateCallback` option lets you hook into template rendering:
+
+```javascript
+widdershins.convert(api, {
+  templateCallback: (templateName, stage, data) => {
+    // stage is 'pre' or 'post'
+    console.log(`${stage} rendering: ${templateName}`);
+    return data; // must return data
+  }
+});
+```
+
+## Supported Input Formats
+
+| Format | Versions | Notes |
+|--------|----------|-------|
+| OpenAPI | 3.0.x | Full support |
+| Swagger | 2.0 | Auto-converted to OAS3 internally |
+| AsyncAPI | 1.x | Topics-based messaging APIs |
+| Semoasa | 0.1.0 | OpenAPI Extension Format |
+| API Blueprint | — | Passthrough (already Markdown) |
+
+## Supported Output Formats
+
+| Format | Use With |
+|--------|----------|
+| Markdown | [Slate](https://github.com/slatedocs/slate), [ReSlate](https://github.com/mermade/reslate), [Shins](https://github.com/mermade/shins) |
+| HTML | [ReSpec](https://github.com/w3c/respec), custom doc sites |
+
+## CLI Usage
+
+The CLI is available but the library API is recommended for app integration:
+
+```bash
+npx widdershins-reborn [options] {input-file|url} [[-o] output-markdown]
+```
+
+```bash
+widdershins-reborn --search false --language_tabs 'python:Python' api.json -o docs.md
+```
+
+Run `widdershins-reborn --help` for all options.
+
+## Custom Templates
+
+Override the default doT.js templates by passing a directory:
+
+```javascript
+widdershins.convert(api, {
+  user_templates: './my-templates'
+});
+```
+
+Template docs:
+- [OpenAPI 3.0 / Swagger 2.0 templates](/templates/openapi3/README.md)
+- [AsyncAPI 1.x templates](/templates/asyncapi1/README.md)
+- [Semoasa templates](/templates/semoasa/README.md)
+
+## Tests
+
+```bash
+npm test
+```
+
+## Credits
+
+* Original project by [Mike Ralphson](https://github.com/Mermade) (Mermade Software)
+* Logo by [@latgeek](https://github.com/LatGeek)
+* httpsnippet support by [@vfernandestoptal](https://github.com/vfernandestoptal)
+
+## License
+
+[MIT](LICENSE) — Original work Copyright (c) 2016 Mermade Software, fork maintained by Sikandar.

package/include/abstract.md

@@ -0,0 +1,2 @@
+This is the Abstract include. It may be found in the widdershins `include` directory,
+it may be modified there or the location overridden with the `--abstract` option.

package/include/sotd.md

@@ -0,0 +1,2 @@
+This is the State of the Document (sotd) include. It may be found in the widdershins `include` directory,
+it may be modified there or the location overridden with the `--sotd` option.

package/lib/apiblueprint.js

@@ -0,0 +1,42 @@
+'use strict';
+
+function convert(api, options) {
+    return new Promise(function (resolve, reject) {
+        api = api.split('\r').join('');
+        var lines = api.split('\n');
+        var title = '';
+        var metadata = [];
+        var index = 0;
+        while ((lines[index].indexOf(':') >= 0) && (index < lines.length)) {
+            metadata.push('> ' + lines[index] + '\n');
+            lines[index] = '';
+            index++;
+        }
+        while (lines[index] && !lines[index].startsWith('# ') && !lines[index].startsWith('==') && (index < lines.length)) {
+            index++;
+        }
+        if ((index < lines.length) && lines[index].startsWith('# ')) {
+            title = lines[index];
+        }
+        else {
+            title = lines[index - 1];
+        }
+        lines.splice(index + 1, 0, ...metadata);
+        api = lines.join('\n');
+        lines = [];
+        api = '\n' + api + '\n';
+        api = '---\ntitle: ' + (title.replace('# ', '')) + '\n' + `language_tabs:
+toc_footers: []
+includes: []
+search: true
+code_clipboard: true
+highlight_theme: darkula
+---
+` + api;
+        resolve(api);
+    });
+}
+
+module.exports = {
+    convert: convert
+};

package/lib/asyncapi1.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const path = require('path');
+const util = require('util');
+
+const yaml = require('yaml');
+const dot = require('dot');
+dot.templateSettings.strip = false;
+dot.templateSettings.varname = 'data';
+
+const common = require('./common.js');
+const resolver = require('oas-resolver');
+const dereference = require('reftools/lib/dereference.js').dereference;
+
+let templates;
+
+function preProcessor(api) {
+    return api;
+}
+
+function convertToToc(source) {
+    let resources = {};
+    for (let t in source.topics) {
+        let topic = source.topics[t];
+        for (var m in topic) {
+            var message = topic[m];
+            var tagName = 'Default';
+            if (message.tags && message.tags.length > 0) {
+                tagName = message.tags[0].name;
+            }
+            if (!resources[tagName]) {
+                resources[tagName] = {};
+                if (source.tags) {
+                    for (let tag of source.tags) {
+                        if (tag.name === tagName) {
+                            resources[tagName].description = tag.description;
+                            resources[tagName].externalDocs = tag.externalDocs;
+                        }
+                    }
+                }
+            }
+            if (!resources[tagName].topics) resources[tagName].topics = {};
+            resources[tagName].topics[t] = { messages: {}, parameters: topic.parameters };
+            resources[tagName].topics[t].messages[m] = message;
+        }
+    }
+    return resources;
+}
+
+function getParameters(params) {
+    for (let p of params) {
+        if (p === false) p = { schema: {} }; // for external $refs when resolve not true
+        if (!p.in) p.in = 'topic';
+        if (typeof p.required === 'undefined') p.required = true;
+        p.safeType = p.schema.type;
+        p.shortDesc = p.description;
+    }
+    return params;
+}
+
+function convertInner(api, options) {
+    return new Promise(function (resolve, reject) {
+        let data = {};
+        if (options.verbose) console.warn('starting deref', api.info.title);
+        data.api = dereference(api, api, { verbose: options.verbose, $ref: 'x-widdershins-oldRef' });
+        if (options.verbose) console.warn('finished deref');
+        data.version = (data.api.info && data.api.info.version && data.api.info.version.toLowerCase().startsWith('v') ? data.api.info.version : 'v' + (data.api.info && data.api.info.version ? data.api.info.version : '1.0.0'));
+        data.widdershins = require('../package.json');
+
+        let header = {};
+        header.title = api.info && api.info.title ? ' ' + data.version : ' 1.0.0';
+
+        header.language_tabs = options.language_tabs;
+        header.headingLevel = Math.max(options.headings || 0, 3);
+
+        header.toc_footers = [];
+        if (api.externalDocs) {
+            if (api.externalDocs.url) {
+                header.toc_footers.push('<a href="' + api.externalDocs.url + '">' + (api.externalDocs.description ? api.externalDocs.description : 'External Docs') + '</a>');
+            }
+        }
+        if (options.toc_footers) {
+            for (var key in options.toc_footers) {
+                header.toc_footers.push('<a href="' + options.toc_footers[key].url + '">' + options.toc_footers[key].description + '</a>');
+            }
+        }
+        header.includes = options.includes;
+        header.search = options.search;
+        header.code_clipboard = options.clipboard;
+        header.highlight_theme = options.theme;
+        header.generator = data.widdershins.name+' v'+data.widdershins.version;
+
+        if (typeof templates === 'undefined') {
+            templates = dot.process({ path: path.join(__dirname, '..', 'templates', 'asyncapi1') });
+        }
+        if (options.user_templates) {
+            templates = Object.assign(templates, dot.process({ path: options.user_templates }));
+        }
+
+        data.options = options;
+        data.header = header;
+        data.templates = templates;
+        data.translations = {};
+        templates.translations(data);
+        data.resources = convertToToc(data.api);
+
+        data.utils = {};
+        data.utils.inspect = util.inspect;
+        data.utils.yaml = yaml;
+        data.utils.getSample = common.getSample;
+        data.utils.getParameters = getParameters;
+        data.utils.schemaToArray = common.schemaToArray;
+        data.utils.getCodeSamples = common.getCodeSamples;
+        data.utils.slugify = common.slugify;
+
+        let content = '';
+        try {
+            if (!options.omitHeader) content += '---\n' + yaml.stringify(header) + '\n---\n\n';
+            content += templates.main(data);
+            content = common.removeDupeBlankLines(content);
+        }
+        catch (ex) {
+            return reject(ex);
+        }
+        content = common.removeDupeBlankLines(content);
+
+        if (options.html) content = common.html(content, header, options);
+
+        resolve(content);
+    });
+}
+
+function convert(api, options) {
+    api = preProcessor(api);
+
+    let defaults = {};
+    defaults.includes = [];
+    defaults.search = true;
+    defaults.clipboard = true;
+    defaults.theme = 'darkula';
+    defaults.language_tabs = [{ 'javascript--nodejs': 'Node.JS' }, { 'javascript': 'JavaScript' }, { 'ruby': 'Ruby' }, { 'python': 'Python' }, { 'java': 'Java' }, { 'go': 'Go' }];
+    defaults.sample = true;
+
+    options = Object.assign({}, defaults, options);
+    options.openapi = api;
+
+    return resolver.optionalResolve(options)
+        .then(function (options) {
+            return convertInner(options.openapi, options);
+        })
+        .catch(function (ex) {
+            throw ex;
+        });
+}
+
+module.exports = {
+    convert: convert
+};
+