モダンでインタラクティブなAPIドキュメントを作る2015年12月22日ishizimaTweetはじめにようやく待望の冬!なんですが、先日20°Cを超える気温を記録しましたね。季節外れの熱気に驚きました。それに今シーズンは暖冬になりそうということで雪不足も懸念されます。スキーの予定も立てられてないんですけど。最近のWebサービスではAPIを公開することも珍しくないと思います。参考になるRESTfulなAPI設計もよく見られるようになりました。そのなかで分かりやすい資料、APIの実行を試しやすい環境を提供できているケースはそう多くないように思います。開発者の立場でいえば、ドキュメント整備にそこまで気を遣う余裕なんてないことが大半かもしれません。一方で、APIを利用する側からすれば最初に目を通すのはドキュメントですから、その出来不出来はAPIに対する評価にもつながります。使って、時間をかけずモダンなAPIドキュメントを作成してみましょう。Apiaryはトップページで謳われる通り、API開発者が利用者に向けてモック環境やドキュメントを一括で提供できるプラットフォームとも呼べるものです。今回は入門ということで、DocBaseのAPIドキュメントをApiary上に移植してみたいと思います。簡単なので詳細は省きますが、適宜サインアップかGitHubアカウントでログインし、新しいAPIドキュメントを作成しましょう。ドキュメントを書くAPIドキュメントを作成すると、テキストエディタ画面になります。ルールに従ってドキュメントを書いていきます。初見では多少面食らうかもしれませんが、すぐ慣れると思います。APIDocBaseのAPIです。Blueprintのエディタ画面以降直後はサンプルが記述されてますので、不慣れでも概要くらいは分かると思います。Blurprintのバージョン、次がAPIテストフォームで使用する接続先の指定です。sandbox環境など用意されていればそちらがいいかも。DocBaseは特にないのでProduction環境を書いちゃいます。その後は通常のMarkdownらしく記述していきます。以下にサンプルを記載します。いう形式でURL1つの記載します。括られた部分はパラメータです。パスの途中でリソースのIDを示したり、クエリパラメータであったり。いう風にAPIの仕様を記述していきます。Blueprintの資料をご覧ください。[GET]指定したドメインのチームのグループのうち、所属しているグループを取得します。}表示例Markdownの表示に追加して、右ペインにAPIの詳細解説が表示されました。押すと、APIへのリクエストを実際に試せるコンソール画面に移行します。押下することで実際にAPIをコールすることができます。待つと、以下のようにレスポンスのヘッダやボディが表示されます。最後に普段のMarkdownを少し拡張して書くだけで、見栄えのいいドキュメントとテスト用のコンソールまで生成されました。API開発者も利用者もハッピーに近付くことができるのではないかと思います。Apiaryには他にもモックなど様々な機能があるようですので、自分ももうちょっと突っ込んで試してみたいと思います。話は変わるのですが、先日RESTfulなAPIの記述を標準化する旨のニュースが報道されました。試してみたいと思います。今回サンプルに使用したAPIに関する情報は以下の通りです。(元ネタ)https://help.docbase.io/posts/45703作例http://docs.docbasesample.apiary.io宣伝DocBaseとはチームを育てるをコンセプトにした情報共有サービスです。メモという形で小さく始められる、エンジニア以外のメンバーでも使いやすい仕組み、情報をまとめて整理できる、柔軟な権限設定で様々なプロジェクトで使えるなど、積極的な情報共有と業務の効率化を実現し、チームの成長を促します。次の記事DocBaseのAPIクライアントのGemを作りました「いいね!」で応援よろしくお願いします!このエントリーに対するコメントコメントはまだありません。date*日本語が含まれない投稿は無視されますのでご注意ください。fax.0422-26-9781お問い合わせはこちらからどうぞ。