widdershins VS slate

You may want to look into other tooling to redesign your Swagger into easier to follow documentation such as: https://github.com/Mermade/widdershins

Widdershins 👎

What if you don’t want Swagger, and prefer something simpler? A popular alternative is Slate—a static API you can build and expose on your URL. Something in-between that’s also worth recommending is a combination of widdershins and api2html. It’ll allow you to generate Slate-like docs from Swagger’s definition.

First you need to install node.js, npm and Widdershins. To install Widdershins run:

You can do both. Widdershins converts an OpenAPI definition to the markdown format used by Slatedocs. https://github.com/mermade/Widdershins

Slate (Free)

https://github.com/slatedocs/slate this ! Big company use it ( stripe etc )

The second most common question being "What framework does Stripe use to build their documentation?" and the answer has unfortunately always been "They use a custom setup they built themselves and isn't available." － so then Slate gets brought up as a suitable replacement

DocuAPI is a multilingual API documentation theme for Hugo created and maintained by Bjørn Erik Pedersen, the lead maintainer and co-creator of Hugo itself. It’s built on top of the Slate API docs generator, which itself was inspired by Stripe’s and PayPal’s API docs. The JavaScript section of DocuAPI has been rewritten from Jquery to AlpineJS.​​​​​​

I've used Slate to document APIs which similarly will produce a local website. You can host that privately or there's built in support to push to github pages if you're hosting it in a github repo. The documentation itself is all written in markdown and managed separate from your API code.

Clone/inspired by stripe docs: https://github.com/slatedocs/slate

If you are going to use Slate from the console you need to install it, along with all its prerequisites, as described here. In Ubuntu you can execute the commands:

Slate - API Generator