APIドキュメント運用の遍歴
株式会社アトラエでエンジニアをしている遠矢 ( @rtuya1219 )です。こちらは、Atrae Advent Calendar 2019 7日目の記事になります。
普段はyentaのサーバサイドを担当しています。
概要
yentaに置けるAPIドキュメントの運用方法がどのように変化してきたかを紹介させていただきます。
阿吽の呼吸でどうにかする期
yentaは弊社で初めて開発したネイティブアプリであり、当初の開発陣の構成としてはアプリエンジニア（なりたて）1名、サーバーサイド1名でした。
もともと慣れ親しんだメンバーでの開発だったこともあり、当時はgithubのissueなどに、下記のようなドキュメントを書いてあとはコミュニケーションを取りながら阿吽の呼吸（？）で開発を進めていました。だいぶ手探り感を感じますね。
# GET: /apis/users/:uid
## パラメータ
- uid: String/ユーザーのUID
- token: String/アクセストークン
## レスポンス
{ 何かしらのjson }
Railsプロジェクト直下にswaggerを置く期
しばらくそのような体制で開発をしていましたが、Androidアプリの開発着手し、手伝ってくれるメンバーが増えたりしたこともあり、ドキュメントの共有をもうすこす明文化しなくてはならなくなってきました。
yentaのサーバサイドの開発は主にRailsを利用している為、swagger-blocks、grape-swagger-rails を利用して本格的なAPIのドキュメント管理を開始しました。
また、apivore というGemを使ってドキュメントと実装されたAPIの乖離を防ぐ取り組みも行なっていました。
ドキュメント管理をめんどくさがる自分としては、ドキュメントを書くこととテストを書くことが半強制的に繋げられるこの運用はよかったと感じています。
ドキュメント単体で運用する期
最近になるとサーバサイドのエンジニアも増えてきました。
上記のGemはRubyのDSLを利用している為、個人的には描きやすくで大好きです。
後輩達の後々を考えた際に、できる限り生のswaggerやOpenAPIの記法に触れていた方が応用が効くだろう（そしてRails直下で肥大化してきたドキュメントを一掃したい）と考えドキュメントを単体で運用する方針に変更しました。
ついでにswaggerファイルを分割管理したい、書くときは気楽に描きたい、Pushしたら勝手にデプロイされていて欲しい、apivoreから参照したいなどなど色々過去の構成なども活かせるような作りにできたと考えています。
基本的には、
1. ローカル環境でDockerを立ち上げて編集する
2. プルリクを作成し、仕様の確認をする
3. masterにマージするとS3にデプロイされ、アプリエンジニアが参照できるようになる
という流れで開発をしています。
現在運用しているドキュメントを元に雑なテンプレートを作成したので興味がある方は適当にご利用くださいませ。
デプロイ部分はCircleCIを利用しているので省かせていただきました。現状だとGithub Actionsなどを選択するのが良いかと思います。こちらの記事など参考になりそうです。
これからは
yentaも比較的長く運用しているアプリなのでAPIの数がかなり多くなってきています。
機能自体のマイクロサービス化を進めたり、ドキュメントの提供方法を工夫することでアプリエンジニアが探しやすくサーバサイドエンジニアも描きやすいドキュメント運用方法を模索していきたいと思います。