「API仕様書からそのまま記述したAPIのお試しみたいなこと出来ないかな?」こんにちは、タカフです。とある案件でAPI仕様書を書くことになりました。API仕様書って書くのが地味に面倒ですよね。API仕様書は大抵誰かに見せる為に作るから体裁を整えないといけない。体裁を整えないといけない=Excel又はWord又はGoogleDocumentで書く。頻繁にAPI仕様書を書いてるわけではない場合テンプレートなんて無いから、体裁含め書いていかなければいけない。僕は、API仕様書を書くとしたらMarkdown形式で書いてhtml変換を圧倒的にオススメ致します。その理由と使い方を下記に述べていきます。API仕様書をMarkdownで書くメリットAPI仕様書をMarkdownで書くと以下のようなメリットが享受出来ます。API仕様書をMarkdownで書くツールの中にはAPIモックサーバーを立ち上げる事もできる順番に説明していきます。Markdownで書くから体裁を一切気にする必要がないMarkdownで書くということは、その記述する内容に最大限に集中出来ます。中身はただのテキストファイルなので、タイピングするには最適です。ExcelやWordで文書を書きだすと、どうしても都度スタイルを気にしてしまいます。ビジネスパーソンの使える時間というのは常に限られているので(そういう認識を以って仕事をしたほうがいいですね。本当にやるべき事以外の事に関しては労力を割く必要はありません。MarkdownでAPI仕様書を書くことだけに集中しましょう。MarkdownならテキストファイルだからGithub等で安全にバージョン管理が出来るExcelやWordもバージョン管理だけなら出来ますが、バージョン差分まで見ようとなると大変ですよね。出来ないことも無いらしいですが、やはり面倒です。それがMarkdownならテキストファイルなのでGit等のリポジトリに登録していると、どこをどう変えたかを明確に見渡すことが出来ます。Git等のリポジトリに登録しておくメリットとしてはもう一つあります。書いたAPI仕様書にすぐにアクセス出来る!!開発案件に携わっていると、一番触るのはソースコードだと思います。API仕様書がソースコードのルートに置かれてあると、今開いているエディタから気軽に開くことが出来ますよね。このメリットが地味に大きいです。どこに置いたかわからない仕様書よりも開くスピードは絶対に早いと思います。僕はこれがメンテナンス性アップにも直結すると思っています。API仕様書をMarkdownで書くツールの中にはAPIモックサーバーを立ち上げる事もできる本記事で紹介している書き方でAPI仕様書を書くと、それがそのままAPIのモックサーバーとして立ち上げることも出来ます。これはとても大切な事です。HTTPリクエストを投げてその結果を処理するのに、そのAPIの開発完了していないとなかなかその処理も実装しにくいですよね。それが後ほど紹介するツールを使えば、モックサーバーが起動するので開発にも使用することが出来るのです。これは開発を加速させます。いうフォーマットがあります。何やらSwagger自体のフォーマットが出来ること多すぎて勉強コストが高い印象を受けてテンションが上がらずやめてしまいました。Blueprintを採用した、という経緯でした。要はAPIの仕様がわかってもらえればいいのだから、そんなところで苦労する必要はないのですよ。書き方すみません色々なところに書いてあるので、ここでは割愛させていただきます。詳しい書き方は下記のページあたりが参考になります。フォーマットのMarkdownで書いたらhtmlに変換していきます。有名なaglioを使いましょう。aglioをインストールまずはaglioをnpmでインストールしましょう。node.jsのインストールするには僕のこちらの記事が参考になります。グローバルインストールでもいいと思います。MarkdownファイルをAPI仕様書のhtmlに変換するaglioをインストールしたら、MarkdownからAPI仕様書として見ることが出来るhtmlに変換してみましょう。使い方は簡単でコマンド一発です。docs/html/api.htmlこれできれいにhtmlファイルを生成してくれます。下記コマンドでリアルタイム変換も可能です。--serverこのコマンドでローカルサーバーが起動して、大抵は以下のURLで確認出来ます。http://127.0.0.1:3000/これでmdファイルを編集して保存したら即htmlに反映されます。これがめちゃくちゃ便利ですね。BlueprintでしっかりとAPI仕様書を書くと、それをそのままAPIのモックサーバーとして動作させることも出来ます。モックサーバーにはdrakovというツールを使います。drakovをインストールこちらもaglio同様にnpmでインストールします。こちらもグローバルにインストールしちゃいましょう。--watchこちらも使い方は簡単です。オプションをつけるだけです。なくしてモックサーバーが起動して、mdファイルで記述したAPIのパスがローカルで叩けるようになります。まとめ本日はAPI仕様書を記述するのに便利なツールの紹介でした。エンジニアの仕事はプログラムを書くだけでありませんね。ドキュメントも立派なお仕事であり、リソースを考えながら仕事しなくてはいけません。いうツールを知ってると知ってないではその後の開発工数に多大な影響を与えるので、存分に活用していった方が結果的に幸せになれますね。【Apache2.4】の.htaccessのIFディレクティブでスラッシュを使う方法この記事を書いた人タカフWebエンジニア・Surface専門家Webのフロントエンド・バックエンド・インフラ(AWS)をワンストップで開発出来る事を強みとしているWebエンジニアです。ブログではWeb系プログラミングTips・オススメPC・ガジェットを中心に情報発信しています。株式会社カフーの社長さん。WordPressプラグインの「Crudiator」を開発。コメントをキャンセルメールアドレスが公開されることはありません。@kahoo365Webのフロントエンド・バックエンド・インフラ(AWS)をワンストップで開発出来る事を強みとしているWebエンジニアです。ブログではWeb系プログラミングTips・オススメPC・ガジェットを中心に情報発信しています。株式会社カフーの社長さん。WordPressプラグインの「Crudiator」を開発。執筆書籍Surfaceの使い方を詳しく解説したSurface専用解説本を出版しました!タカフ@WebエンジニアWeb系プログラミングTips・オススメPC・プログラミングスクールを中心に情報発信しています。PCの中でもノートPCが好きで、本当の買うべきノートPCに絞って紹介することが多いです。ITエンジニア歴はいつのまにか15年程。システム開発・Web運営にいそしむ日々。株式会社カフーの社長さん。WordPressのプラグイン開発もしています。Search人気記事1【レビュー】半年使ってわかった。27インチ4Kの最強モニターな件。