弥生開発者ブログ弥生開発者ブログ2016-12-22Grape+SwaggerでAPIのドキュメント作成を自動化したこんにちは、Misoca開発チームのいっしーです。11月からMisocaにJoinしました。10年ほど東京にいたので、未知の土地に新鮮な気持ちでいます。名古屋の好きなところはB級グルメがたくさんあるところ、こわいところは学生時代に学んでいた関数型言語OCamlや自然言語の形式理論の話がナチュラルに通じてしまうところです。v3が先日リリースされました。見積書や取引先をAPI経由で扱えるようになっています。www.misoca.jpまた、技術面ではGrapeとgrape-swaggerを新たに導入しました。今回はこれらについて紹介したいと思います。Rails標準のControllerでリクエストを受け付け、結果をjson形式などでレスポンスを返す形を取っていました。APIドキュメントは手書きしていました。問題点やはりというべきか、v1では変更への追従がひとつの課題でした。Web版Misocaの仕様変更をAPIに反映させることも、APIの変更をドキュメントへ反映させることも、毎回漏れなく行うには結構な手間がかかりました。楽したい......。上記の問題を解決するために、まずはドキュメントの作成を自動化することにしました。コードからのドキュメントの生成には、AutodocやApipie-railsなどがありましたが、標準化されたフォーマットということでSwaggerを採用しました。SwaggerではSwaggerUIと呼ばれるAPIドキュメントビューワーも提供されています。コードの実装には、Grapeを使用しました。GrapeはRubyでRESTlikeなAPIを実装するためのフレームワークで、コードをきれいに記述できたり、APIのルーティングをDSLで記述することができます。今回、Grape+Swaggerで実現したいことは以下の二つです。コードからドキュメントを自動生成できるサンプルレスポンスを表示できるgemのインストールまずは、以下のgemをインストールしました。次にAPI本体を実装します。以下にファイルを置いています。役割的にはcontroller他のAPIと同じような場所に置きたかったautoloadの効くディレクトリに置きたかったそして、以下のような実装になっています。共通メソッドのinclude。endenddescで記載している部分が、APIの説明としてSwaggerで表示されます。レスポンススキーマの実装そして、サンプルレスポンスを自動生成するために、app/presenter/api_entity以下にレスポンススキーマを定義します。最後に、API本体をapp/controllers/api/v3/root.rb内でマウントし、Swagger形式のドキュメントを作成します。確認することができます。このアドレスをSwaggerUI右上のテキストボックスに入力することで、ドキュメントがSwaggerUIで表示されます。完成!以上を行なってSwaggerUIで表示されたものがこちらです。説明文やリクエストパラメータ、サンプルレスポンスなどがドキュメントに反映されていることがわかると思います。実際に動くものがみたい方はこちらでどうぞ。苦労した点GrapeはApplicationControllerを継承していないため、そこで定義していた変数が一部使えなくなりました。具体的には、現在ログインしているユーザを表すcurrent_userなどです。これらは認証を行うために必要なので、別途、実装しました。helperを使ってGrapeの拡張を行います。いまのところv3でしか使わないので、app/controllers/api/v3以下にauthenticate.rbを作成し、その中でcurrent_userなどを定義します。endendまとめAPIドキュメントを自動生成するようにしたことで、コード修正とドキュメント修正の二重苦から解放され、保守がかなり楽になりました。11:00関連記事2017-08-28💸PayPalのAPI認証キーの妥当性検証mzpです。最近、実装した機能についての話を書きます。最初は...2017-04-21設定きりわけ大作戦Misoca開発チームの黒曜(@kokuyouwind)です。[PayPal編]皆さん、こんにちは。弥生は第23回Quesに協賛します。引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。