restapiのドキュメント作成ツール iodocs を試してみる

# iodocs

REST APIのドキュメント作成&実行ツール。
nodeとredisを使っている。

⇒ https://github.com/mashery/iodocs

# インストール

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

* [node.jsがない場合はこちら](http://qiita.com/teratsyk/items/51d64010cb341b54491b)  

* [redisがない場合はこちら](http://qiita.com/teratsyk/items/122c7625b9ace6c882dc)

# サンプル作成

`schemas`で扱うデータ構造を、`resources`でエンドポイントを定義する。

```shell-session:iodocs/public/data/sample.json
{
    "basePath": "http://localhost",
    "name": "sample API v1.0",
    "protocol": "rest",
    "publicPath": "/v1",
    "version": "1.0",
    "schemas": {
        "user": {
            "properties": {
                "id": {
                    "title": "id",
                    "type": "integer",
                    "required": true,
                    "description": "ユーザID"
                },
                "name": {
                    "title": "name",
                    "type": "string",
                    "required": true,
                    "description": "氏名"
                },
                "status": {
                    "title": "status",
                    "type": "integer",
                    "required": true,
                    "description": "ユーザステータス"
                }
            }
        }
    },
    "resources": {
        "User Resources": {
            "methods": {
                "userList": {
                    "name": "ユーザ一覧取得ーザ情報の一覧を取得する",
                    "httpMethod": "GET",
                    "path": "/users",
                    "parameters": {
                        "user_status": {
                            "description": "ユーザのステータス情報",
                            "location": "query",
                            "required": false,
                            "type": "integer"
                        }
                    }
                },
                "userInsert": {
                    "name": "ユーザ登録",
                    "description": "ユーザ情報を登録する",
                    "httpMethod": "POST",
                    "path": "/users",
                    "request": {
                        "$ref": "user"
                    },
                    "ExpectResponses": [
                        {
                            "Format": "json",
                            "schema": {
                                "$ref": "user"
                            }
                        }
                    ]
                },
                "userDetail": {
                    "name": "ユーザ詳細取得",
                    "description": "ユーザ情報の詳細を取得する",
                    "httpMethod": "GET",
                    "path": "/users/{id}",
                    "parameters": {
                        "user_id": {
                            "description": "ユーザID",
                            "location": "path",
                            "required": true,
                            "type": "integer"
                        }
                    },
                    "ExpectResponses": [
                        {
                            "Format": "json",
                            "schema": {
                                "$ref": "user"
                            }
                        }
                    ]
                },
                "userUpdate": {
                    "name": "ユーザ更新",
                    "description": "ユーザ情報を更新する",
                    "httpMethod": "PUT",
                    "path": "/users/{id}",
                    "request": {
                        "$ref": "user"
                    },
                    "parameters": {
                        "user_id": {
                            "description": "ユーザID",
                            "location": "path",
                            "required": true,
                            "type": "integer"
                        }
                    },
                    "ExpectResponses": [
                        {
                            "Format": "json",
                            "schema": {
                                "$ref": "user"
                            }
                        }
                    ]
                },
                "userDelete": {
                    "name": "ユーザ削除",
                    "description": "ユーザを削除する",
                    "httpMethod": "DELETE",
                    "path": "/users/{id}",
                    "parameters": {
                        "user_id": {
                            "description": "ユーザID",
                            "location": "path",
                            "required": true,
                            "type": "integer"
                        }
                    }
                }
            }
        }
    }
}
```

```shell-session:iodocs/public/data/apiconfig.json
{
    {
        ...
    },
    # 以下を追記
    "sample": {
        "name": "sample v1 API"
    }
}
```

# 確認する

ブラウザで http://localhost:3000 にアクセス

# 課題

* レスポンスサンプルの定義`ExpectResponses`が効いていない
  * [対応済みっぽいが。。](https://github.com/mashery/iodocs/issues/16)
  * それならRAMLとかで書いた方が見やすいかも。


* URIパラメータ、クエリパラメータ、リクエストボディを全てフォームで入力する形式なので、叩くにはchromeのDHCなどの方が使いやすいかも。

* 「RAML等+DHC」か、「iodocs」か、という感じ？

* コードとドキュメントのメンテを考えるとswaggerの方がよい？