というわけで、前回のMarkdown形式のドキュメントからAPIドキュメントを作るジェネレータをバージョンアップしました。

リポジトリは変えてます。

Github - axcelwork/torus-apidoc
torus-apidoc - Demo

---

2019/7/1 追記
コマンドラインから扱えるように axcelwork/torus-apidoc-cli というのを作成しました。

---

前回と同じように、npmでサーバを立ち上げて、Markdownを編集すると自動的にHTMLとPDFを出力してくれます。

デザインの大幅変更

前回は左メニューとメインの2カラム構成でしたが、今回は

• 左メニュー
• パラメータ等記載エリア
• ソースコード記載エリア

の3カラム構成にしました。
1000px以下だと左メニューが消えて2カラムに。
700px以下だと1カラムになるように調整しています。

印刷時のフッター追加

前回からと違うところで言えば、印刷時のフッターにコピーライトを入れれるようにしました。
設定値自体はpackage.jsonに保持し、マークダウンやPDFに変換する時に、設定値を取得し反映しています。

package.json

{
  "name": "torus",
  // 省略
  "copy": "Copyright © Example Inc.",
  "scripts": {
  // 省略
}

こんな感じで設定値を`package.json'に記載します。
取得方法は下記でOK。

./lib/html_pdf/html_pdf.js

const options = {
  "base": base_path,
  "border": "10px",
  "footer": {
    "height": "20px",
    "contents": {
      default: '<div style="font-size: 8px; text-align: center; color: #333;">' + process.env.npm_package_copy + '</div>'
    }
  },
};

あとは、印刷したときに余白設定によって、端のほうが切れたりするかもしれないので、html_pdfのオプションでborderを設定しています。

./lib/marked/marked.js

fs.writeFileSync("resources/html/tmp/copy.ejs", process.env.npm_package_copy)

process.envに諸々設定値が格納されてくるので、取得するだけです。

印刷時の改ページ対応

印刷をしたときに、要素の途中で切れたりしますよね。
そんな時は page-break-inside: avoidを使用する。
とりあえずどの要素で改ページ処理が発生するかわからないので、全要素に適用する。

style.css

html,body,div,span,h1,h2,h3,h4,h5,h6,p,cite,em,pre,img,small,strong,sub,sup,dl,dt,dd,ol,ul,li,form,label,table,tbody,tfoot,thead,tr,th,td,article,aside,dialog,figure,footer,nav,
section {
  margin: 0;
  padding: 0;
  border: 0;
  outline: 0;
  font-weight: 500;
  font-style: normal;
  background: transparent;
  box-sizing: border-box;
  line-break: strict;
  letter-spacing: 0.1rem;
  color: #333;
  /* ▼これ */
  page-break-inside: avoid;
}

まとめ

これでエンジニア以外でもAPI仕様書が作れるぞ！やったー。