概要
APIドキュメントの作成は開発とは切っても切れない関係です。しかしながらHTTPメソッドやヘッダーなど書かなくちゃいけないことが多くドキュメント作成作業を想像すると重い腰が上がりません。
実案件においてもドキュメント作成をAPI Blueprint で行なったことがありますが、結構な時間を取られてしまいました。
個人的にAPIドキュメントツールとして使ったことがあるのは API Blueprint と Swaggerですが、どちらも真面目にゼロベースで書き始めると結構大変な作業だとわかります。
そこでなんとか楽できないかなあと探していたら便利なAPIMATICというサービスを発見したのでその紹介をしようと思います。
APIMATIC
APIMATICはどんなサービスかというと、すでにあるフォーマットのドキュメントを任意のフォーマットに変換してくれるサービスです。
たとえば、Postman Collectionで書かれたものをSwagger形式(YAML)に変換したり、API Blueprint形式(apib)に変換したりすることができます。
APIMATICが対応しているフォーマットの対応表
| ドキュメント | input | output |
|---|---|---|
| API Blueprint | ○ | ○ |
| Swagger 1.0 - 1.2 | ○ | Swagger 1.2 |
| Swagger 2.0 JSON | ○ | ○ |
| Swagger 2.0 YAML | ○ | ○ |
| WADL - W3C 2009 | ○ | ○ |
| WSDL 1.1 - W3C | ○ | ○ |
| Google Discovery | ○ | - |
| RAML 0.8 - 1.0 | ○ | ○ |
| I/O Docs - Mashery | ○ | - |
| HAR 1.2 | ○ | - |
| Postman Collection 1.0 - 2.0 | ○ | ○ |
| APIMATIC Format | ○ | ○ |
| Mashape | ○ | - |
| Open API Spec 3.0.0 (JSON) | ○ | ○ |
| Open API Spec 3.0.0 (YAML) | ○ | ○ |
APIMATICの使い方
APIMATICの使い方はとても簡単です。こちらのページにアクセスして少しスクロールすると下のような画面になります。
File Description Upload に変換する前のドキュメントをアップロードして Target Description Formatで任意のフォーマットを選択して下さい。
最後にConvert Nowをクリックすればいい感じに変換してくれます。
所感
試しにDynamoDBからGetでデータの一覧を取得するAPIを作成し、POSTMANでのテストからエクスポートしてAPIMATICでSwagger(YAML)に変換し、Swaggerhubのエディターでドキュメントを確認する、という流れをやってみたのですが結構いい感じなのではないかと思っています。
右側に貼り付けているのはAPIMATICで変換したYAMLです。
Try it outでテストするとResponse bodyにDynamoDBから取得してきたデータが返ってきています。
あとがき
APIドキュメントは開発を円滑に行う上では大切なものですがあまり気の進む作業ではありません。もっと楽にドキュメント作成できる方法があればぜひ教えて下さい。