Ask HN: Is OpenAPI Documentation Superior?

Re:Ask HN: Is OpenAPI Documentation Superior? by Meic on Thursday March 25, 2021 @03:12AM (#26577268)

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

[ Parent | on HN ]

Re:Ask HN: Is OpenAPI Documentation Superior? by bigiain on Thursday March 25, 2021 @08:53PM (#26587663)

Oooh, nice. That looks potentially useful.

For people who haven’t clicked the link, this assumes you’re defining your API in OpenAPI/Swagger/a few other options, and (one directionally) converts it to suitable formats for static publishing:

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.

[ Parent | on HN ]

Re:Ask HN: Is OpenAPI Documentation Superior? by gwittel on Saturday March 27, 2021 @01:28AM (#26600158)

Widdershins works pretty well. IIRC their README also links to a CLI tool that wraps Widdershins.

I containerized it and added some wrapper scripts so we can just drop the YAML spec in our repo and have build automation to generate/deploy a web site with all the relevant docs.

[ Parent | on HN ]

Re:Ask HN: Is OpenAPI Documentation Superior? by hirokib on Thursday March 25, 2021 @05:31PM (#26585672)

I saw this and I'm definitely leaning towards it now given what was said in this thread. Thanks!

[ Parent | on HN ]