swagger
APIBlueprint

APIドキュメント作成を時短する

概要

APIドキュメントの作成は開発とは切っても切れない関係です。しかしながらHTTPメソッドやヘッダーなど書かなくちゃいけないことが多くドキュメント作成作業を想像すると重い腰が上がりません。
実案件においてもドキュメント作成をAPI Blueprint で行なったことがありますが、結構な時間を取られてしまいました。
個人的にAPIドキュメントツールとして使ったことがあるのは API BlueprintSwaggerですが、どちらも真面目にゼロベースで書き始めると結構大変な作業だとわかります。

そこでなんとか楽できないかなあと探していたら便利なAPIMATICというサービスを発見したのでその紹介をしようと思います。

APIMATIC

スクリーンショット 2017-10-16 23.37.09.png

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の使い方はとても簡単です。こちらのページにアクセスして少しスクロールすると下のような画面になります。

スクリーンショット 2017-10-17 0.20.15.png

File Description Upload に変換する前のドキュメントをアップロードして Target Description Formatで任意のフォーマットを選択して下さい。

最後にConvert Nowをクリックすればいい感じに変換してくれます。

所感

試しにDynamoDBからGetでデータの一覧を取得するAPIを作成し、POSTMANでのテストからエクスポートしてAPIMATICでSwagger(YAML)に変換し、Swaggerhubのエディターでドキュメントを確認する、という流れをやってみたのですが結構いい感じなのではないかと思っています。

screencapture-app-swaggerhub-apis-gcyata-test-1-0-0-1508168650839.png

右側に貼り付けているのはAPIMATICで変換したYAMLです。

スクリーンショット 2017-10-17 0.48.33.png

Try it outでテストするとResponse bodyにDynamoDBから取得してきたデータが返ってきています。

あとがき

APIドキュメントは開発を円滑に行う上では大切なものですがあまり気の進む作業ではありません。もっと楽にドキュメント作成できる方法があればぜひ教えて下さい。