Widdershins - Short Review

Product Overview: Widdershins

Introduction

Widdershins is a powerful tool designed to convert API definitions from various formats, including OpenAPI 3.0, OpenAPI 2.0 (formerly Swagger), AsyncAPI 1.x, and Semoasa, into static documentation in Markdown format. This tool is particularly useful in the API documentation pipeline, helping developers and documentation teams generate high-quality, customizable documentation.

Key Features

API Definition Support

Widdershins supports a wide range of API definition formats, including OpenAPI 3.0, OpenAPI 2.0 (Swagger), AsyncAPI 1.x, and Semoasa. This versatility makes it a comprehensive solution for different API documentation needs.

Customizable Templates

The tool uses templates compiled with doT.js, allowing for extensive customization. Users can edit the default templates or create their own by copying the existing templates into a specified directory. This feature enables tailored documentation that fits specific project requirements.

Code Samples and Language Support

Widdershins can generate code samples in multiple languages, and users can specify language tabs using the --language_tabs option. The tool also supports unified JavaScript and Node.js code samples, with additional support for PHP. Users can turn off generic code samples or automatically generate a list of languages for code samples.

Output Formats

In addition to Markdown, Widdershins can output documentation in HTML and ReSpec formats directly, providing flexibility in how the documentation is presented and used.

Advanced Options

• Schema Handling: Widdershins allows users to expand or limit the depth of schema examples, and there is an option to omit schemas entirely by customizing the templates.
• Authorization Header: The tool can include a generated Authorization header in OpenAPI code samples, which can be omitted if necessary.
• Template Callbacks: Users can use callback functions to manipulate the data before and after each template runs, providing further customization.

User-Friendly CLI and Programmatic Interface

Widdershins can be used via the command line interface (CLI) or integrated into JavaScript code. The CLI offers various options such as specifying output files, themes for syntax highlighting, and more. For programmatic use, Widdershins provides a converter function that can be called with custom options.

Functionality

• Conversion Process: Widdershins takes an API definition file (in JSON or YAML format) and converts it into Markdown documentation. This process can be customized using various options and templates.
• Syntax Highlighting: The tool supports syntax highlighting using themes from highlight.js, enhancing the readability of the generated documentation.
• Integration with Renderers: The output Markdown is compatible with renderers like Slate, ReSlate, and Shins, making it easy to integrate into existing documentation workflows.

Installation and Usage

Widdershins can be installed globally using npm (npm install -g widdershins) or locally within a project. It can be run from the command line or integrated into a Node.js application. The tool comes with extensive documentation and examples to help users get started quickly.

In summary, Widdershins is a robust and flexible tool for generating high-quality API documentation from various API definition formats. Its customizable templates, advanced options, and support for multiple output formats make it an essential component in any API documentation pipeline.