「API仕様書を書くことになったけど、どうやって書けばいいかな？」
「API仕様書からそのまま記述したAPIのお試しみたいなこと出来ないかな？」
こんにちは、タカフです。
とある案件でAPI仕様書を書くことになりました。API仕様書って書くのが地味に面倒ですよね。
API仕様書は大抵誰かに見せる為に作るから体裁を整えないといけない。
体裁を整えないといけない＝Excel又はWord又はGoogleDocumentで書く。
でも頻繁にAPI仕様書を書いてるわけではない場合テンプレートなんて無いから、体裁含め書いていかなければいけない。
これがツラい。
なので僕は、API仕様書を書くとしたらMarkdown形式で書いてhtml変換を圧倒的にオススメ致します。
その理由と使い方を下記に述べていきます。
API仕様書をMarkdownで書くメリット
API仕様書をMarkdownで書くと以下のようなメリットが享受出来ます。
– Markdownで書くから体裁を一切気にする必要がない
– MarkdownならテキストファイルだからGithub等で安全にバージョン管理が出来る
– API仕様書をMarkdownで書くツールの中にはAPIモックサーバーを立ち上げる事もできる
順番に説明していきます。
Markdownで書くから体裁を一切気にする必要がない
Markdownで書くということは、その記述する内容に最大限に集中出来ます。中身はただのテキストファイルなので、タイピングするには最適です。
ExcelやWordで文書を書きだすと、どうしても都度スタイルを気にしてしまいます。
ビジネスパーソンの使える時間というのは常に限られているので（そういう認識を以って仕事をしたほうがいいですね。）、
本当にやるべき事以外の事に関しては労力を割く必要はありません。
MarkdownでAPI仕様書を書くことだけに集中しましょう。
MarkdownならテキストファイルだからGithub等で安全にバージョン管理が出来る
ExcelやWordもバージョン管理だけなら出来ますが、バージョン差分まで見ようとなると大変ですよね。
出来ないことも無いらしいですが、やはり面倒です。
それがMarkdownならテキストファイルなのでGit等のリポジトリに登録していると、どこをどう変えたかを明確に見渡すことが出来ます。
しかも、Git等のリポジトリに登録しておくメリットとしてはもう一つあります。
書いたAPI仕様書にすぐにアクセス出来る！！
開発案件に携わっていると、一番触るのはソースコードだと思います。
API仕様書がソースコードのルートに置かれてあると、今開いているエディタから気軽に開くことが出来ますよね。
このメリットが地味に大きいです。どこに置いたかわからない仕様書よりも開くスピードは絶対に早いと思います。
僕はこれがメンテナンス性アップにも直結すると思っています。
API仕様書をMarkdownで書くツールの中にはAPIモックサーバーを立ち上げる事もできる
本記事で紹介している書き方でAPI仕様書を書くと、それがそのままAPIのモックサーバーとして立ち上げることも出来ます。
これはとても大切な事です。
API仕様書を書いているということは当然それを使って開発を進めることになりますが、
当然HTTPリクエストを投げてその結果を処理するのに、そのAPIの開発完了していないとなかなかその処理も実装しにくいですよね。
それが後ほど紹介するツールを使えば、モックサーバーが起動するので開発にも使用することが出来るのです。
これは開発を加速させます。
API仕様書をMarkdownで書くにはAPI Blueprintの書式で書こう
APIをMarkdownで書くには、API Blueprint と Swagger というフォーマットがあります。
僕は、この2つなら API Blueprintを推します！
そもそも事の発端はAWS のAPI Gatewayで作業していたら、SwaggerというものでAPI仕様書を取り込んでそのまま動作させるみたいなことが出来ることを知って、Swaggerを使いだしたのですが、
何やらSwagger自体のフォーマットが出来ること多すぎて勉強コストが高い印象を受けてテンションが上がらずやめてしまいました。
そして、その後にAPI Blueprintを知って使ってみたら非常にシンプルだったので、API仕様書のMarkdownのフォーマットにはAPI Blueprintを採用した、という経緯でした。
要はAPIの仕様がわかってもらえればいいのだから、そんなところで苦労する必要はないのですよ。
API Blueprint の書き方
すみません色々なところに書いてあるので、ここでは割愛させていただきます。詳しい書き方は下記のページあたりが参考になります。
https://qiita.com/the40san/items/0f673a9fe8b72c4b0225
Markdown形式からhtml形式に変換
API BlueprintのフォーマットのMarkdownで書いたらhtmlに変換していきます。一番有名なaglioを使いましょう。
aglioをインストール
まずはaglioをnpmでインストールしましょう。
node.jsのインストールするには僕のこちらの記事が参考になります。
npm install -g aglio
今後よく使うので -g でグローバルインストールでもいいと思います。
MarkdownファイルをAPI仕様書のhtmlに変換する
aglioをインストールしたら、MarkdownからAPI仕様書として見ることが出来るhtmlに変換してみましょう。
使い方は簡単でコマンド一発です。
aglio -i docs/src/api.md -o docs/html/api.html
これできれいにhtmlファイルを生成してくれます。
また、下記コマンドでリアルタイム変換も可能です。
aglio -i api.md --server
このコマンドでローカルサーバーが起動して、大抵は以下のURLで確認出来ます。
http://127.0.0.1:3000/
これでmdファイルを編集して保存したら即htmlに反映されます。これがめちゃくちゃ便利ですね。
APIモックサーバーを作る
API BlueprintでしっかりとAPI仕様書を書くと、それをそのままAPIのモックサーバーとして動作させることも出来ます。
モックサーバーにはdrakovというツールを使います。
drakovをインストール
こちらもaglio同様にnpmでインストールします。こちらもグローバルにインストールしちゃいましょう。
npm install -g drakov
drakovでモックサーバーを起動する
drakov -f docs/src/api.md --watch
こちらも使い方は簡単です。書き連ねたAPI仕様書のmdファイルのパスを指して、 --watch オプションをつけるだけです。
程なくしてモックサーバーが起動して、mdファイルで記述したAPIのパスがローカルで叩けるようになります。
まとめ
本日はAPI仕様書を記述するのに便利なツールの紹介でした。
エンジニアの仕事はプログラムを書くだけでありませんね。ドキュメントも立派なお仕事であり、リソースを考えながら仕事しなくてはいけません。
こういうツールを知ってると知ってないではその後の開発工数に多大な影響を与えるので、存分に活用していった方が結果的に幸せになれますね。
現場からは以上です。
