{"id":13668507,"url":"https://github.com/mermade/widdershins","last_synced_at":"2025-05-14T09:09:16.349Z","repository":{"id":37686541,"uuid":"70106620","full_name":"Mermade/widdershins","owner":"Mermade","description":"OpenAPI / Swagger, AsyncAPI \u0026 Semoasa definitions to (re)Slate compatible markdown","archived":false,"fork":false,"pushed_at":"2024-06-04T23:50:09.000Z","size":1738,"stargazers_count":1490,"open_issues_count":89,"forks_count":322,"subscribers_count":17,"default_branch":"main","last_synced_at":"2024-10-29T15:22:25.494Z","etag":null,"topics":["api","asyncapi","documentation","openapi","openapi3","semoasa","slate","swagger"],"latest_commit_sha":null,"homepage":"https://mermade.github.io/reslate","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mermade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-05T23:09:13.000Z","updated_at":"2024-10-27T17:29:50.000Z","dependencies_parsed_at":"2023-02-09T08:01:47.916Z","dependency_job_id":"3ddedf11-32a0-4dcd-b558-034b8d2f8433","html_url":"https://github.com/Mermade/widdershins","commit_stats":{"total_commits":728,"total_committers":55,"mean_commits":"13.236363636363636","dds":"0.17032967032967028","last_synced_commit":"ee80786792e8fa1bf1b9a48975514e359af7d1c0"},"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mermade%2Fwiddershins","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mermade%2Fwiddershins/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mermade%2Fwiddershins/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mermade%2Fwiddershins/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mermade","download_url":"https://codeload.github.com/Mermade/widdershins/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247968291,"owners_count":21025823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","asyncapi","documentation","openapi","openapi3","semoasa","slate","swagger"],"created_at":"2024-08-02T08:00:38.956Z","updated_at":"2025-04-09T03:09:21.600Z","avatar_url":"https://github.com/Mermade.png","language":"JavaScript","funding_links":[],"categories":["OpenAPI / Swagger"],"sub_categories":[],"readme":"# widdershins\nOpenAPI / Swagger / AsyncAPI / Semoasa definition to [Slate](https://github.com/slatedocs/slate) /\n[ReSlate](https://github.com/mermade/reslate) compatible markdown\n\n![Build](https://img.shields.io/travis/Mermade/widdershins/master.svg) [![Tested on APIs.guru](https://api.apis.guru/badges/tested_on.svg)](https://APIs.guru) [![Tested on Mermade OpenAPIs](https://img.shields.io/badge/Additional%20Specs-419-brightgreen.svg)](https://github.com/mermade/OpenAPI_specifications)\n[![Known Vulnerabilities](https://snyk.io/test/npm/widdershins/badge.svg)](https://snyk.io/test/npm/widdershins)\n\n\u003cimg src=\"http://mermade.github.io/widdershins/logo.png\" width=\"247px\" height=\"250px\" /\u003e\n\n### Widdershins *adverb*:\n* In a direction contrary to the sun's course;\n* anticlockwise;\n* helping you produce static documentation from your OpenAPI 3.0 / Swagger 2.0 / AsyncAPI 1.x / Semoasa 0.1.0 definition\n\n![Widdershins screenshot](https://mermade.github.io/widdershins/screenshot.png)\n\n### News\n\n* Version 4.0 changes:\n  * Now uses Promises not callbacks\n  * Option to output html directly, and to ReSpec format\n  * Unified JavaScript and Node.js code-samples, PHP added\n  * `restrictions` column (`readOnly`/`writeOnly`) added to schema templates\n  * Numerous bug fixes\n* 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.\n* You may limit the depth of schema examples using the `--maxDepth` option. The default is 10.\n* To omit schemas entirely, please copy and customise the `main.dot` template.\n* As of v3.1.0 Widdershins includes a generated `Authorization` header in OpenAPI code samples. If you wish to omit this, see [here](/templates/openapi3/README.md).\n\n### To install\n\n* Clone the git repository, and `npm i` to install dependencies, or\n* `npm install -g widdershins` to install globally\n\n### Getting started\n\nWiddershins is generally used as a stage in an API documentation pipeline. The pipeline begins with an API definition in OpenAPI 3.x, OpenAPI 2.0 (fka Swagger), API Blueprint, AsyncAPI or Semoasa format. Widdershins converts this description into markdown suitable for use by a **renderer**, such as [Slate](https://github.com/slatedocs/slate), [ReSlate](https://github.com/mermade/reslate), [Shins](https://github.com/mermade/shins)  (*deprecated*) or html suitable for use with [ReSpec](https://github.com/w3c/respec).\n\nIf you need to create your input API definition, [this list of available editors](https://apis.guru/awesome-openapi3/category.html#editors) may be useful.\n\nMore in-depth documentation is [available here](https://mermade.github.io/widdershins).\n\n### Examples\n\n```\nnode widdershins --search false --language_tabs 'ruby:Ruby' 'python:Python' --summary defs/petstore3.json -o petstore3.md\n```\n\n### Options\n\n| CLI parameter name | JavaScript parameter name | Type | Default value | Description |\n| --- | --- | --- | --- | --- |\n| --clipboard | options.clipboard | `boolean` | `true` | Sets the value of the `code_clipboard` property in the heading, so that markdown processors can include clipboard support. |\n| --customApiKeyValue | options.customApiKeyValue | `string` | `ApiKey` | Set a custom API key value to use as the API key in generated code examples. |\n| --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. |\n| --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. |\n| --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. |\n| --omitHeader | options.omitHeader | `boolean` | `false` | Omit the header / YAML front-matter in the generated Markdown file. |\n| --resolve | options.resolve | `boolean` | `false` | Resolve external $refs, using the `source` parameter or the input file as the base location. |\n| --shallowSchemas | options.shallowSchemas | `boolean` | `false` | When referring to a schema with a $ref, don't show the full contents of the schema. |\n| 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. |\n| --summary | options.tocSummary | `boolean` | `false` | Use the operation summary as the TOC entry instead of the ID. |\n| --useBodyName | options.useBodyName | `boolean` | Use original param name for OpenAPI 2.0 body parameter. |\n| -v, --verbose | options.verbose | `boolean` | `false` | Increase verbosity. |\n| -h, --help | options.help | `boolean` | `false` | Show help. |\n| --version | options.version | `boolean` | `false` | Show version number. |\n| -c, --code | options.codeSamples | `boolean` | `false` | Omit generated code samples. |\n| --httpsnippet | options.httpsnippet | `boolean` | `false` | Use httpsnippet to generate code samples. |\n| -d, --discovery | options.discovery | `boolean` | `false` | Include schema.org WebAPI discovery data. |\n| -e, --environment | N/A | `string` | None | File to load config options from. |\n| -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. |\n| -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. |\n| --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`. |\n| -m, --maxDepth | options.maxDepth | `integer` | 10 | Maximum depth to show for schema examples. |\n| -o, --outfile | N/A | `string` | None | File to write the output markdown to. If left blank, Widdershins sends the output to stdout. |\n| -r, --raw | **inverse** of options.sample | `boolean` | `false` | Output raw schemas instead of example values. |\n| -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. |\n| -t, --theme | options.theme | `string` | darkula | Syntax-highlighter theme to use. |\n| -u, --user_templates | options.user_templates | `string` | None | Directory to load override templates from. |\n| -x, --experimental | options.experimental | `boolean` |  | Use httpSnippet for multipart mediatypes. |\n| -y, --yaml | options.yaml | `boolean` | `false` | Display JSON schemas in YAML format. |\n|  | options.templateCallback | `function` | None | A `function` that is called before and after each template (JavaScript code only). |\n|  | options.toc_footers | `object` | A map of `url`s and `description`s to be added to the ToC footers array (JavaScript code only). |\n\nIn Node.JS code, create an options object and pass it to the Widdershins `convert` function, as in this example:\n\n```javascript\nconst converter = require('widdershins');\nlet options = {}; // defaults shown\noptions.codeSamples = true;\noptions.httpsnippet = false;\n//options.language_tabs = [];\n//options.language_clients = [];\n//options.loadedFrom = sourceUrl; // only needed if input document is relative\n//options.user_templates = './user_templates';\noptions.templateCallback = function(templateName,stage,data) { return data };\noptions.theme = 'darkula';\noptions.search = true;\noptions.sample = true; // set false by --raw\noptions.discovery = false;\noptions.includes = [];\noptions.shallowSchemas = false;\noptions.tocSummary = false;\noptions.headings = 2;\noptions.yaml = false;\n//options.resolve = false;\n//options.source = sourceUrl; // if resolve is true, must be set to full path or URL of the input document\nconverter.convert(apiObj,options)\n.then(str =\u003e {\n  // str contains the converted markdown\n})\n.catch(err =\u003e {\n  console.error(err);\n});\n```\n\nTo only include a subset of the pre-defined language-tabs, or to rename their display-names, you can override the `options.language_tabs`:\n\n```javascript\noptions.language_tabs = [{ 'go': 'Go' }, { 'http': 'HTTP' }, { 'javascript': 'JavaScript' }, { 'javascript--node': 'Node.JS' }, { 'python': 'Python' }, { 'ruby': 'Ruby' }];\n```\n\nThe `--environment` option specifies a JSON or YAML-formatted `options` object, for example:\n\n```json\n{\n  \"language_tabs\": [{ \"go\": \"Go\" }, { \"http\": \"HTTP\" }, { \"javascript\": \"JavaScript\" }, { \"javascript--node\": \"Node.JS\" }, { \"python\": \"Python\" }, { \"ruby\": \"Ruby\" }],\n  \"verbose\": true,\n  \"tagGroups\": [\n    {\n      \"title\": \"Companies\",\n      \"tags\": [\"companies\"]\n    },\n    {\n      \"title\": \"Billing\",\n      \"tags\": [\"invoice-create\", \"invoice-close\", \"invoice-delete\"]\n    }\n  ]\n}\n```\n\nYou 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.\n\nIf you need to support a version of Slate \\\u003cv1.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.\n\nIf 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`:\n\n```javascript\noptions.language_clients = [{ 'shell': 'curl' }, { 'node': 'request' }, { 'java': 'unirest' }];\n```\n\nIf 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`.\n\nTo see the list of languages and clients supported by httpsnippet, [click here](https://github.com/Kong/httpsnippet/tree/master/src/targets).\n\nThe `loadedFrom` option is only needed where the OpenAPI / Swagger definition does not specify a host, and (as per the OpenAPI [specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields)) the API endpoint is deemed to be based on the source URL\nthe definition was loaded from.\n\nTo see the list of highlight-js syntax highlighting themes, [click here](https://highlightjs.org/static/demo/).\n\nSchema.org WebAPI discovery data is included if the `discovery` option above is set `true`. See the W3C [WebAPI Discovery Community Group](https://www.w3.org/community/web-api-discovery/) for more information.\n\n## Language tabs\n\nWiddershins supports the `x-code-samples` [vendor-extension](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#operation-object-vendor-extensions) to completely customise your documentation. Alternatively, you can edit the default code-samples in the `templates` sub-directory, or override them using the `user_templates` option to specify a directory containing your templates.\n\nWiddershins 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.\n\n## Templates\n\nBy 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.\n\nThe 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`.\n\nThis 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](http://meldmerge.org/) or [WinMerge](http://winmerge.org).\n\n### Template syntax\n\nTemplates are compiled with [doT.js](https://github.com/olado/doT#readme).\n\nTemplates 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:\n\n* [Swagger 2.0 / OpenAPI 3.0.x template parameters](/templates/openapi3/README.md)\n* [AsyncAPI 1.x template parameters](/templates/asyncapi1/README.md)\n* [Semoasa 0.1.0 template parameters](/templates/semoasa/README.md)\n\nTo 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}}`.\n\nTo 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:\n```\n|Name|In|Type|Required|Description|\n|---|---|---|---|---|\n{{~ data.parameters :p}}|{{=p.name}}|{{=p.in}}|{{=p.safeType}}|{{=p.required}}|{{=p.shortDesc || 'none'}}|\n{{~}}\n```\n\nFor 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:\n```\n{{? data.api.components \u0026\u0026 data.api.components.securitySchemes }}\n{{#def.security}}\n{{?}}\n```\n\nYou 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:\n```\n{{ {\nlet message = \"Hello!\";\n} }}\n\n{{=message}}\n```\n\n### Template callbacks\n\nThe `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.\n\nWiddershins passes these variables to the callback function:\n- `templateName`: The name of the template, such as `main`.\n- `stage`: Whether Widdershins is calling the callback function before (`pre`) or after (`post`) the template.\n- `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.\n\nFor example, this JavaScript code prints the name of the template and the processing stage in the output Markdown:\n```javascript\n'use strict';\n\nconst converter = require('widdershins');\nconst fs = require('fs');\n\nlet options = {};\noptions.templateCallback = myCallBackFunction;\n\nfunction myCallBackFunction(templateName, stage, data) {\n  let statusString = \"Template name: \" + templateName + \"\\n\";\n  statusString += \"Stage: \" + stage + \"\\n\";\n  data.append = statusString;\n  return data;\n}\n\nconst apiObj = JSON.parse(fs.readFileSync('defs/petstore3.json'));\n\nconverter.convert(apiObj, options)\n.then(str =\u003e {\n  fs.writeFileSync('petstore3Output.md', str, 'utf8');\n});\n```\n\n## Tests\n\nTo run a test-suite:\n\n```\nnode testRunner {path-to-APIs}\n```\n\nThe test harness currently expects `.yaml` or `.json` files and has been tested against\n\n* [APIs.guru](https://github.com/APIs-guru/OpenAPI-directory)\n* [Mermade OpenAPI definitions collection](https://github.com/mermade/OpenAPI-definitions)\n\n### Comparison between this and other OpenAPI / Swagger to Slate tools\n\n[Blog posting](https://dev.to/mikeralphson/comparison-of-various-openapiswagger-to-slate-conversion-tools) by the author of Widdershins.\n\n### Acknowledgements\n\n* [@latgeek](https://github.com/LatGeek) for the logo.\n* [@vfernandestoptal](https://github.com/vfernandestoptal) for the httpsnippet support.\n\n### Widdershins in the wild\n\nPlease feel free to add a link to your API documentation here.\n\n* [GOV.UK Content API v1.0.0](https://content-api.publishing.service.gov.uk/reference.html)\n* [GOV UK Digital Marketplace API v1.0.0](https://alphagov.github.io/digitalmarketplace-api-docs/#digital-marketplace-api-v1-0-0)\n* [Capital One API](https://www.capitalone.co.uk/developer/api/)\n* [Cognite Data API](http://doc.cognitedata.com/)\n* [SpeckleWorks API](https://speckleworks.github.io/SpeckleSpecs)\n* [Bank by API](https://tbicr.github.io/bank-api/bank-api.html)\n* [Open EO API](https://open-eo.github.io/openeo-api-poc/apireference/index.html)\n* [Split Payments API](http://docs.split.cash/)\n* [LeApp daemon API](https://leapp-to.github.io/shins/index.html)\n* [Shutterstock API](https://api-reference.shutterstock.com/)\n* [Shotstack Video Editing API](https://shotstack.io/docs/api/index.html)\n* [Admetricks API](http://dev.admetricks.com/)\n* [Eqivo API](https://eqivo.org/)\n\n### Widdershins and ReSlate\n\n* `Widdershins` works well with Slate, but for a solely Node.js-based experience, why not try the [ReSlate](https://github.com/mermade/reslate) port?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmermade%2Fwiddershins","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmermade%2Fwiddershins","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmermade%2Fwiddershins/lists"}