OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown. 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, ReSlate, Shins (deprecated) or html suitable for use with ReSpec. 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 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. Widdershins supports the x-code-samples vendor-extension to completely customize your documentation.
Features
- Widdershins supports the use of multiple language tabs with the same language
- By default, Widdershins uses the templates in its templates/ folder to generate the Markdown output
- Customize the templates and copy some or all of them to a folder and pass their location to the user_templates parameter
- Templates are compiled with doT.js
- Templates have access to a data object with a range of properties based on the document context
- Option to output html directly, and to ReSpec format
Project Samples
