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がない場合はこちら

• redisがない場合はこちら

サンプル作成

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

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"
                        }
                    }
                }
            }
        }
    }
}

iodocs/public/data/apiconfig.json

{
    {
        ...
    },
    # 以下を追記
    "sample": {
        "name": "sample v1 API"
    }
}

確認する

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

課題

• レスポンスサンプルの定義ExpectResponsesが効いていない

  • 対応済みっぽいが。。
  • それならRAMLとかで書いた方が見やすいかも。

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

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

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