Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
Help us understand the problem. What is going on with this article?

続・MarkDownからAPIドキュメントを作る

More than 1 year has passed since last update.

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

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

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


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


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

デザインの大幅変更

前回は左メニューとメインの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仕様書が作れるぞ!やったー。

axcelwork@github
わくわく・わーく
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away