Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
118
Help us understand the problem. What is going on with this article?
@horimislime

iodocsで便利なREST APIドキュメントを作成する

More than 5 years have passed since last update.

wikiとかでドキュメントを書くのが面倒で、良いツールを探していたらiodocsというnode製ツールを見つけた。

これを使うとドキュメント作成が楽になるだけじゃなく、 ドキュメント上のformからAPIリクエストを試せて便利っぽい。

iodocs-screen.png

普段APIドキュメントを見つつcurlとかでリクエスト送信して試してたのが、全てドキュメント上で完結して良さげ。

使い方

mashery/iodocsからcloneしてアプリを起動すると、FoursquareやLinkedin APIを叩くサンプルをすぐに試せる。redisが必要なのでserver起動を忘れずに。

~/ $ git clone http://github.com/mashery/iodocs.git
~/iodocs $ npm install
~/iodocs $ redis-server &
~/iodocs $ npm start

ドキュメントは public/data/ 下にjson形式で書くようになっていて、新しくドキュメントを追加したい場合は以下のように記述する。

my-api.json
{
    "endpoints": [
        {
            "name": "Public API",
            "methods": [
                {
                    "MethodName": "ユーザ情報取得API",
                    "Synopsis": "会員の詳細情報が取れるよ",
                    "HTTPMethod": "GET",
                    "URI": "/user",
                    "RequiresOAuth": "N",
                    "parameters": [
                        {
                            "Name": "user_id",
                            "Required": "Y",
                            "Default": "",
                            "Type": "string",
                            "Description": "会員IDです"
                        }
                    ]
                }
            ]
        },
        {
            "name": "Private API",
            "methods": [
                {
                    "MethodName": "ユーザ設定変更API",
                    "Synopsis": "ユーザの設定情報が見れるよ",
                    "HTTPMethod": "POST",
                    "URI": "/user/setting",
                    "RequiresOAuth": "Y"
                }
            ]
        }
    ]
}

あとは public/data/apiconfig.json に作成したドキュメントのjsonファイル名と、formからリクエストを投げるAPIサーバの情報を書いておく。

apiconfig.jsonに追記
"my-api": {
    "name": "My API",
    "protocol": "http",
    "baseURL": "127.0.0.1",
    "publicPath": "/api/v1",
    "auth": "key",
    "keyParam": "api_key_var_name",
    "headers": {
        "Accept": "application/json"
    }
}

あとはnodeを立ち上げるだけ。APIリクエスト用のformもjsonの内容から自動生成してくれる。

ドキュメントを不慣れな記法で書きつつレイアウトやらfontサイズやら考えなくて済むし、APIコールを試す側の手間も省けて便利。

118
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
118
Help us understand the problem. What is going on with this article?