DIVEJavaScriptの設定を有効にしてご利用ください。無効の場合、当サイトを正常にご利用できません。mio.satohWebでも組み込みでも、何かのシステムを構築したことがある方ならご存知でしょう。開発というものは、「プログラムを書く作業」よりも、その前の「仕様を決めて文書化する作業」の方がずっとカロリーが高いものです。最近ちょっとしたAPIを作る機会があり、やはりAPI仕様設計のしんどさと闘いました。Blueprintという規格とそれに対応するツールを使うことで、そのしんどさが相当な具合で和らぐことがわかりました。Blueprintを全力で推していく記事です。Blueprintは、APIの仕様設計や連携開発を効率的に進めるためのドキュメント仕様です。Markdownに従った仕様になっているので、そのまま眺めてもある程度理解できるのですが、Blueprintの強みはなんと言ってもその拡張性です。Blueprintに対応したレンダリングツールを使うと、このような見目麗しい仕様書がコマンド一発で書き出せます。仕様書からAPIモックサーバーを立てられるMarkdownで書いた仕様書が、やはりコマンド一発でモックサーバーになります。これが何より便利で、まだAPIを渡すまでは時間がかかるけどそろそろフロント側の開発を進めないと...というときに、Blueprintの仕様書をgitに上げてしまえば、それがそのままモックサーバー(あるいはスタブAPI)になります。Markdownなので読みやすく管理しやすい中身は平易なMarkdown記法なので、編集が楽で導入コストも低いです。それ故にdiffが把握しやすいというメリットがあります。(反面、ある程度自由に書けてしまうので、ファットになってくるとメンテナンス性が下がるという特性も。)他のAPIドキュメンテーションツールとの違い他のものは機能を比較できるほど使っていないので、簡単な紹介にとどめます。Swaggerhttps://swagger.io/Blueprintより有名かもしれません。記述言語はYAMLまたはJSON。公式でGUIエディターやモックサーバーまで提供しており、多機能でリッチです。RAMLhttps://raml.org/その名前から想像できるように、記述言語はYAML。Swaggerの人気に押され気味のようですが、YAMLが好きなら選択肢に入るかも。言語仕様的に、BlueprintよりSwaggerの方が大規模開発向けかなと思います。できることはほぼ同じなので、好みで選んでOKです。仕様書を書く早速書いてみましょう。公式のチュートリアルはこちらです。DIVEの社員一人のデータを取ってくるAPIの仕様書という設定で書いてみました。テキストエディタはどれを使っても問題ないですが、当然ながらMarkdownのハイライトに対応したものがよいです。[/member/get/{id}]一人のMONSTERのデータを取得します。1A現在のBlueprintのフォーマット名です。無くても問題ないそうですが、おまじないとして唱えておきます。認証(Authentication)何かして取得したtokenをheaderで渡す冒頭の説明文は好きに書けます。いう文章を縛りなく書けるのがMarkdown記法に準拠しているBlueprintのいいところですね。hogeの形で記述すると、APIのグルーピングが出来ます。書き出したhtmlで言うところの、サイドバーのトグル部分にあたります。[/member/get/{id}]この部分でAPIのパスとタイトルを指定します。{hoge}の形で記述すると変数として受け取る値になります。ユーザーIDこのようにリスト形式でパラメータを指定します。Modelでレスポンスモデルを定義しています。XXX*でレスポンスコードを、その下にレスポンスボディを記述します。Data][]という呪文で呼び出しています。呼び出しを使わず、直接Modelをを記述することも出来ます。拡張子を"apib"として、プロジェクトのディレクトリに保存します。Blueprintの公式サイトを見ると、様々なツールが紹介されています。https://apiblueprint.org/tools.htmlこのツール集のなかで、"Renderers"にリストアップされているものがHTML書き出しツールです。メジャーなものにSnowboardやAglioがありますが、私はあまり日本で紹介されていないSnowboardが気に入ったので、こちらを紹介します。Snowboardの特長として、この後紹介するモックサーバー機能まで有しており、これ一つでツールが完結するのです。https://github.com/bukalapak/snowboardインストールnpmでインストールするだけです。monster.apibこれだけでhtmlに出力されます。出力したサンプルはこちら。Blueprintが出力するhtmlは見やすくて綺麗。(Aglioでも負けず劣らず綺麗に書き出せますが)このhtmlと、元のBlueprint仕様書をgitに上げて、バージョン管理するといい感じです。モックサーバーを立ち上げる最後にローカルのモックサーバーを立ててみましょう。書き出しと同様にSnowboardで実現できます。ちなみに、他にもDrakovというモックサーバーツールがよく紹介されていますが、シンプルなモックサーバーとしてはSnowboardの機能で必要十分でした。:8087----------------------------------------------------------------mockコマンドを叩くだけで、サーバーが立ち上がりました。表示を見ると、ちゃんとGETで指定のパスのリクエストを待ち受けていることがわかります。2010}]}ちゃんと想定通りのレスポンスが得られました。Blueprintのようなツールを使うと、API仕様設計が劇的に効率化します。後工程にも優しくなって、いいことづくめなのです。最新のビルドツール「Parcel」で開発環境をサクッと立ち上げる。2019.02.07脱jQuery!?、Swiper使ってみた。Vue.jsでWebアプリをつくろう!2018.09.09脱jQuery!?、anime.js使ってみた。2018.04.20脱jQuery!?、Barba.js使ってみた。2017.11.17脱jQuery!?、はじめました。最新のビルドツール「Parcel」で開発環境をサクッと立ち上げる。Typeではじめる構造化データモンスターダイブの2019年を振り返る。創業10周年を振り返る。