Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mermade/widdershins
OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown
https://github.com/mermade/widdershins
api asyncapi documentation openapi openapi3 semoasa slate swagger
Last synced: about 2 months ago
JSON representation
OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown
- Host: GitHub
- URL: https://github.com/mermade/widdershins
- Owner: Mermade
- License: mit
- Created: 2016-10-05T23:09:13.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2024-03-18T11:38:46.000Z (6 months ago)
- Last Synced: 2024-04-14T09:58:22.093Z (5 months ago)
- Topics: api, asyncapi, documentation, openapi, openapi3, semoasa, slate, swagger
- Language: JavaScript
- Homepage: https://mermade.github.io/reslate
- Size: 1.66 MB
- Stars: 1,450
- Watchers: 16
- Forks: 315
- Open Issues: 86
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# widdershins
OpenAPI / Swagger / AsyncAPI / Semoasa definition to [Slate](https://github.com/slatedocs/slate) /
[ReSlate](https://github.com/mermade/reslate) compatible markdown
 [](https://APIs.guru) [](https://github.com/mermade/OpenAPI_specifications)
[](https://snyk.io/test/npm/widdershins)
### 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](/templates/openapi3/README.md).
### 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](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).
If you need to create your input API definition, [this list of available editors](https://apis.guru/awesome-openapi3/category.html#editors) may be useful.
More in-depth documentation is [available here](https://mermade.github.io/widdershins).
### 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:
```javascript
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`:
```javascript
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:
```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"]
}
]
}
```
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 \ {
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
* [APIs.guru](https://github.com/APIs-guru/OpenAPI-directory)
* [Mermade OpenAPI definitions collection](https://github.com/mermade/OpenAPI-definitions)
### Comparison between this and other OpenAPI / Swagger to Slate tools
[Blog posting](https://dev.to/mikeralphson/comparison-of-various-openapiswagger-to-slate-conversion-tools) by the author of Widdershins.
### Acknowledgements
* [@latgeek](https://github.com/LatGeek) for the logo.
* [@vfernandestoptal](https://github.com/vfernandestoptal) for the httpsnippet support.
### Widdershins in the wild
Please feel free to add a link to your API documentation here.
* [GOV.UK Content API v1.0.0](https://content-api.publishing.service.gov.uk/reference.html)
* [GOV UK Digital Marketplace API v1.0.0](https://alphagov.github.io/digitalmarketplace-api-docs/#digital-marketplace-api-v1-0-0)
* [Capital One API](https://www.capitalone.co.uk/developer/api/)
* [Cognite Data API](http://doc.cognitedata.com/)
* [SpeckleWorks API](https://speckleworks.github.io/SpeckleSpecs)
* [Bank by API](https://tbicr.github.io/bank-api/bank-api.html)
* [Open EO API](https://open-eo.github.io/openeo-api-poc/apireference/index.html)
* [Split Payments API](http://docs.split.cash/)
* [LeApp daemon API](https://leapp-to.github.io/shins/index.html)
* [Shutterstock API](https://api-reference.shutterstock.com/)
* [Shotstack Video Editing API](https://shotstack.io/docs/api/index.html)
* [Admetricks API](http://dev.admetricks.com/)
* [Eqivo API](https://eqivo.org/)
### Widdershins and ReSlate
* `Widdershins` works well with Slate, but for a solely Node.js-based experience, why not try the [ReSlate](https://github.com/mermade/reslate) port?