はじめに
フロントサイドとサーバーサイドのエンジニアが、分業する際に大事なものはなんでしょうか。
コンポーネントの切り方の認識合わせ？？そうかもしれません。
それと同様に大切なのが、API仕様の共有の仕方だと思います。
今回、私たちのチームではサーバサイドのAPIの開発に先立ち、フロントサイドの開発をする箇所が出てきたため、
Open API仕様記述ツールを投入して仕様共有してみることとしました。
そもそもOpen API仕様って
Open API仕様（OpenAPI-Specification）とは、一言で言ってしまえばREST APIを記述する為の仕様。yamlやjsonに近い形式で記述することができます。
GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository
もともとSwaggerっていうフレームワークがあって、USでデファクトスタンダードとなり、のちにその仕様がOpenAPI-Specificationのベースとして採用されたようですね。(2015年)
RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに － Publickey
Open API仕様/Swaggerの何がいいか
この決められたフォーマットにそって記述することで、
- コードで管理できる
- API mockingしたりtestできる
- validateもtypescriptのentityも発行できる
- 言語非依存のmicroservice interfaceとなり、汎用的である
などなどのメリットが得られるようです。
wikiなどでのDocument管理は維持管理辛いからもうやめよう。。。。
ツール選びで重視するポイント
- 安い
- チームで共有管理が楽
- サーバー用意してくれてAPI Mockingできると嬉しい
- json schemaを生成してくれる(今回はgraphQLやgRPCなどのツールは対象外)
JSON Schema生成ツールでSwagger対抗馬
JSON Schema 中心設計 - FlowType から RAML まで - - Qiita
要はJSON Schemaを、どういうフォーマットのinputで吐き出させるか。
(Swagger、Raml、API Blueprintのフォーマットが一般的)
1.Raml
yamlでゴリゴリかく系。
ツールも結構豊富。
Swaggerより読みやすいらしいが、コミュニティの繁栄などもかなり押されている印象
Swaggerのファイル仕様が不満だったのでRAMLを触って比較してみる - 冥冥乃志
API mockingやtestまで面倒見てくれるSwagger-hub的プラットホームは見つかりませんでした。
2.API Blueprint
apiary.ioというプラットホームが使っているフォーマットが普及した感じらしい。markdown形式で記述できるのが特徴。
Specを見るとなかなか辛い。
Modelに名前をつけて使いまわしたり、仕様の記述を複数ファイルに分割する事ができず、時間が経つにつれメンテが困難になっていく。
JS書く人とサーバAPI書く人が別々で、JS書く人が最初に動き出してうまくAPI仕様も設計できるのなら選択してもよいかも。
(GoConの前哨戦として各種API仕様記述フォーマットについて概要を述べておく - Qiitaより引用)
なるほど、でもmarkdownっぽくかけるのは魅力的。
apiary.io
さっきでてきたツール。API mockingまで面倒見てくれる。GitHUb syncでチームで管理できるようです。
Swaggerのフォーマットも選択できるみたいだけど、それならSwagger hubでよくないか感。しかも 10メンバー99ドルでお安くはない。
3.yamlとか書かないでなんとかしたい(GUI Editor)
全く中のスキーマ仕様を知らなくてもGUIでぽちぽちできる系
学習コストが低く、そういう意味でコミュニケーションもフロントとバック間で取りやすそうだ。
フロントサイドもいじることを考えると、理想的っちゃ理想的です。
Apicurio Studio
OpenAPI-GUI v3.0.0に近いかな？？
GitHub syncで管理できる。お値段の面でも、OSSなので無料なのが素晴らしいです。
が、しかし
hubとして使えたりAPImock立てたりtestできるようになる開発は次のフェイズのようです。。
それができれば最強のツールでは？？これからも随時ロードマップを追いかけて、適宜検証していきたい。
Roadmap | Apicurio Studio
Stoplight
APImockも立てれてtestもできる、素晴らしい。
しかし一人月25ドルかかるので辛い。
暫定結論
ここまで調べて、だいたいのAPI mockingまでカバーしたプラットホーム系ソフトウェアは高いから一旦諦めるという結論に。（Swagger-hubも高い(５メンバー月に90ドル)）
そこで、とりあえずdocker imageやIDEのプラグインなど周辺ツールが優秀なのもあり、hub以外のSwaggerツールを使っていくことに。(結局長いものに巻かれた感。必要であれば自社でmockサーバ立ててって感じになるかもしれない。)
Swagger EditorとSwagger UIとSwaggerのモックAPIサーバーをdocker-compose化してみた - Qiitaのように、チームでAPI仕様を共有、管理していけるのが理想。
これから運用して、辛くなっては他のツールに浮気しながら溜まった知見を随時まとめていこうかと思います。
こんなツールがいけてて安いよっていうのがあれば、どんどん教えていただけると大変助かります！よろしくお願いします。
参考文献
GoConの前哨戦として各種API仕様記述フォーマットについて概要を述べておく - Qiita
API設計ツール「Swagger」が素晴らしい｜萬田大作 / コルクBooks代表｜note
OpenAPI.Tools
Swaggerとは何か？ - プログラマでありたい