Apiary でモダンでインタラクティブなAPIドキュメントを作る

はじめに

ようやく待望の冬！なんですが、先日20℃を超える気温を記録しましたね。季節外れの熱気に驚きました。それに今シーズンは暖冬になりそうということで雪不足も懸念されます。まだスキーの予定も立てられてないんですけど。

さて、最近のWebサービスではAPIを公開することも珍しくないと思います。参考になるRESTfulなAPI設計もよく見られるようになりました。ただ、そのなかで分かりやすい資料、APIの実行を試しやすい環境を提供できているケースはそう多くないように思います。開発者の立場でいえば、ドキュメント整備にそこまで気を遣う余裕なんてないことが大半かもしれません。一方で、APIを利用する側からすれば最初に目を通すのはドキュメントですから、その出来不出来はAPIに対する評価にもつながります。
そういうわけで、今回はWeb APIのドキュメント環境である Apiary を使って、時間をかけずモダンなAPIドキュメントを作成してみましょう。

Apiary とは

Powerful API Design Stack. Built for Developers.
Work together to quickly design, prototype, document and test APIs

https://apiary.io/ より

Apiaryはトップページで謳われる通り、API開発者が利用者に向けてモック環境やドキュメントを一括で提供できるプラットフォームとも呼べるものです。
今回は入門ということで、DocBaseのAPIドキュメントをApiary上に移植してみたいと思います。

アカウント作成

簡単なので詳細は省きますが、適宜サインアップかGitHubアカウントでログインし、新しいAPIドキュメントを作成しましょう。
外部に公開する場合は Private Documentation をOFFにします。

ドキュメントを書く

APIドキュメントを作成すると、テキストエディタ画面になります。ここで API Blueprint のルールに従ってドキュメントを書いていきます。基本的には Markdown の拡張です。初見では多少面食らうかもしれませんが、すぐ慣れると思います。

書き方

FORMAT: 1A
HOST: https://api.docbase.io/

# DocBase API

DocBaseのAPIです。

## 接続先ホスト

https://api.docbase.io

API Blueprintのエディタ画面以降直後はサンプルが記述されてますので、不慣れでも概要くらいは分かると思います。先頭行はAPI Blurprintのバージョン、次がAPIテストフォームで使用する接続先の指定です。sandbox環境など用意されていればそちらがいいかも。DocBaseは特にないのでProduction環境を書いちゃいます。
その後は通常のMarkdownらしく記述していきます。

API周りの記述

以下にサンプルを記載します。そんなに難しいことはなく、 ## タイトル [PATH] という形式でURL1つの記載します。そのURLに対する操作を ### タイトル [リクエストメソッド] で並べて記載します。 {domain} のように {} で括られた部分はパラメータです。パスの途中でリソースのIDを示したり、クエリパラメータであったり。

### の中で、+ Parameters から始まるパラメータの説明、 + Request 、 + Response [レスポンスコード] (コンテントタイプ) という風にAPIの仕様を記述していきます。

詳細はAPI Blueprintの資料をご覧ください。

https://github.com/apiaryio/api-blueprint

## グループ情報  [/teams/{domain}/groups]

### 所属グループ一覧取得 [GET]

指定したドメインのチームのグループのうち、所属しているグループを取得します。

+ Parameters

    + domain (string) - ドメイン名

+ Request

    + Headers

            X-DocBaseToken: abcdefghij0123456789
            X-Api-Version: 1

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "DocBase"
            },
            {
                "id": 2,
                "name": "kray-internal"
            }
        ]

+ Response 403 (application/json)

    + Body

            {
                "error": "forbidden",
                "messages": [
                    "Forbidden"
                ]
            }

表示例

Markdownの表示に追加して、右ペインにAPIの詳細解説が表示されました。
右上の Switch to Console を押すと、APIへのリクエストを実際に試せるコンソール画面に移行します。

このコンソールからパラメータなどリクエストに必要な情報を適宜設定して、 Call Resource を押下することで実際にAPIをコールすることができます。
少し待つと、以下のようにレスポンスのヘッダやボディが表示されます。

最後に

普段のMarkdownを少し拡張して書くだけで、見栄えのいいドキュメントとテスト用のコンソールまで生成されました。API開発者も利用者もハッピーに近付くことができるのではないかと思います。Apiaryには他にもモックなど様々な機能があるようですので、自分ももうちょっと突っ込んで試してみたいと思います。

話は変わるのですが、先日RESTfulなAPIの記述を標準化する旨のニュースが報道されました。気になりますね。ということで、次回は Swagger を試してみたいと思います。

今回サンプルに使用したAPIに関する情報は以下の通りです。

DocBase のAPIドキュメント (元ネタ)

https://help.docbase.io/posts/45703

作例

http://docs.docbasesample.apiary.io

宣伝

DocBaseとは

チームを育てるをコンセプトにした情報共有サービスです。
メモという形で小さく始められる、エンジニア以外のメンバーでも使いやすい仕組み、情報をまとめて整理できる、柔軟な権限設定で様々なプロジェクトで使えるなど、積極的な情報共有と業務の効率化を実現し、チームの成長を促します。

詳しくはこちらから。
https://docbase.io