DOCSEARCHbyAlgolia
Submit Docs

widdershins

repository·main·Indexed 23 days ago

https://github.com/mermade/widdershins

A tool that converts OpenAPI (Swagger), AsyncAPI, and Semoasa definitions into Markdown compatible with documentation renderers such as Slate, ReSlate, Shins, or as HTML for ReSpec. It provides both a command-line interface and a JavaScript API for Node.js applications, allowing for programmatic conversion and integration into build pipelines. Widdershins supports customizable templates using doT.js and offers configuration options for language tabs, search settings, and Table of Contents generation.

Tokens
10K
Snippets
21
Records
42
Agent score
79%

What's inside widdershins

  1. Get started with Widdershins

    main
    Widdershins is a tool used in API documentation pipelines to convert API definitions (OpenAPI 3.x, OpenAPI 2.0/Swagger, API Blueprint, AsyncAPI, or Semoasa) into Markdown. This Markdown is designed to be rendered by tools like Slate, ReSlate, or Shins, or as HTML for ReSpec.

  2. Customize Widdershins templates

    main

    By default, Widdershins uses internal templates located in its templates/ folder. To customize the Markdown output, copy the templates (including .dot files and .def partials) to a local directory and provide the path to this directory using the user_templates parameter in your configuration.

    Important Considerations:

    • To override a .dot template, you must also copy any child .def partials it references.
    • 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.
    • It is recommended to copy all .dot and .def files to your user templates directory to avoid missing dependencies.
    • Use a visual diff tool (like Meld or WinMerge) to merge changes from Widdershins updates into your custom templates.

  4. Convert OpenAPI/Swagger files using the Widdershins CLI

    main

    You can convert a valid OpenAPI 3.0 or Swagger 2.0 file to Markdown using the widdershins command. You must specify the input file and the output file using the -o option. You can pass configuration options directly as CLI flags or via an environment file.

    widdershins --environment env.json swagger.json -o myOutput.md

  5. Convert OpenAPI files using the Widdershins JavaScript API

    main
    For programmatic conversion within a Node.js application, use the Widdershins JavaScript API. This allows you to integrate OpenAPI to Markdown conversion directly into your build pipelines or tools.

  6. Structure OpenAPI/Swagger documents for Table of Contents (TOC) generation

    main

    Widdershins uses the top-level tags object in an OpenAPI/Swagger specification to generate the primary entries in the Table of Contents.

    To create a hierarchical TOC:

    1. First Level: Define entries using the tags object. Ensure each operation links to a tag.
    2. Second Level: Provide a concise operationId for each operation to generate the second level of TOC entries.

    Note: If an operation contains multiple tags, Widdershins will only use the first tag to prevent duplicate information in the TOC.

  9. Structure input API documents for Table of Contents (TOC) generation

    main
    To ensure Widdershins generates a proper Table of Contents (TOC) in the output Markdown, you must structure your input API documents according to specific Markdown patterns. Follow the TOC structure guide to optimize how endpoints and sections are indexed.