Markdown形式のAPI設計書を作る方法

API設計書なんてSwaggerで作成したものをどこかでホストして共有すればOKですよね。

僕もそう考えていたのですが、先日とある理由でAPI設計書をファイル形式（HTML以外）で受け渡す必要が出てきまして、 OpenAPIで作成した定義をMarkdown形式に変換できる方法はないかなと調べたところ、便利なライブラリがあったので紹介します。

出来上がるもの

Markdownプレビューしたものがこちら

使用したライブラリ

OpenAPIやSwaggerからMarkdownを作成するライブラリがありました。

Mermade/widdershins

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown - Mermade/widdershins

https://github.com/Mermade/widdershins

使い方

まずはライブラリを追加

$ yarn add widdershins

OpenAPIのyamlを用意

API定義は、こちらのリポジトリのpetstore.yamlを使って試しました。
package.jsonと同階層にファイルをコピーしておきます。

OAI/OpenAPI-Specification

The OpenAPI Specification Repository. Contribute to OAI/OpenAPI-Specification development by creating an account on GitHub.

https://github.com/OAI/OpenAPI-Specification

OpenAPI定義からMarkdownを作成

package.jsonにビルド用のコマンドを追加して、yarn buildを実行すると、 petstore.mdが出力されます。

追加したビルド用コマンドはこちらです。オプションは必要に応じて変更してください。

"scripts": {
  "build": "yarn widdershins",
  "widdershins": "widdershins --language_tabs http:Http --expandBody --resolve --summary petstore.yaml -o petstore.md"
},

出力されたMarkdownファイルをVSCodeのMarkdownプレビューなどで見れば、最初に紹介した画像の通りの見え方になると思います。