REST APIのインターフェイス仕様をSwaggerのAPIドキュメントで一元的に定義・管理することで、モバイルとサーバエンジニア間のコミュニケーションを齟齬なく円滑に進めることができます。
さらに、SwaggerのSwiftコードのジェネレート機能を活用することで、工数の削減と品質の向上を図り生産性を高める方法をご紹介します。
Swaggerで始めるAPI定義管理とコードジェネレート
4 月からフリーランスです。
サーバーの方とコラボレーションしながら開発していると思いますが、思っているものと違うものが入ってくることがあると思う。
齟齬をなくして、円滑にすすめるために重要かと思う。値の方がJSONからはわからないとか、本番ではNULLがはいってきたとか。そうしたことを定義することで手戻りが少なくなる
大手が立ち上げた規格化？プロジェクトで採用されている
このような定義内容があります。
専用エディタが提供されていてブラウザで動きます。Specファイルからドキュメントをジェネレイトして見られるようにしたり、モックサーバーを作ることができます。
エディタです。
ローカルでも動きます。右手が、定義が可視化されたものです。
左に定義がSwagger SpecとしてYAMLで書かれています。
Path＝EndpointとDefinition＝JSONのモデル定義です。
定義を間違えるとすぐ分かる
Getエンドポイントを定義してみます。
Arrayだとか、requireで必須だとか定義できる。
レスポンスは200と400で定義して、それぞれどのような内容が返るかを定義できる。
モデル定義。左に定義すると右に可視化されている。モデル定義の入れ子も可能。Int32とInt64を分けることが出来る。Statusのようなものはenumで定義できる。
exampleを定義しておくと、モックサーバーがその値を返す。何も定義しなければその型のデフォルト値が返る。
モックサーバーができて、APIサーバーが完成していなくてもクライアントを開発できるし、仕様に齟齬がない。
コードジェネレート出来る。なぜコードジェネレートしたいか。折角定義したのに人間が実装する時に間違えたら勿体無い
Swagger Codegen 様々な言語に対応している。Kotlinも5月ぐらいに対応。新しい言語にも積極的に対応している
Swiftの場合
実行方法
Podのバージョンをインクリメント出来ると便利
どんなオプションが有るかはこちらで確認
リクエスト部のAPIと、モデル、通信用クラスなどがGenerateされる。
Cadableに準拠したモデルができました。requireでないところはOptionalになります。
通信部分はSuccessかErrorかのコールバックが基本です。
リクエスト部分は柔軟にカスタマイズできます
MultifileSwaggerというのを作っている人がいる
タグを打ってCocoaPodsをタグのバージョンに合わせるように徹底する
成熟してきている中で、ノウハウも溜まってきている。開発効率や品質向上がフォーカスされていくのではないか。そうした中でAPI定義やコードジェネレートが一助になれば
QA
- 既にSwaggerで作られたわけではないサーバーがあるとして、別に定義を用意するという使い方もあるでしょうか
- 両サイドの認識合わせに定義を明示することは意味があるのではないかと思います。ジェネレートしたコードにリプレースする意味があるか。うまく入れ替えられるなら良いと思う。インターフェースさえうまく導入できそうであれば活用できると思う
- 定義を書き出したがサーバーが準拠していない場合
- 曖昧だったところとの不整合が起きてクラッシュが起きる可能性はあるが、それはその曖昧な運用だったということだと思うので、リリースまでに修正できるなら、より品質の高い状態でリリースでき、今後の運用もしやすくなると思います。
- API以外とかで使えますか、たとえば、定数や型などでやりたい時にAPI以外に、アプリ側と他のサーバーサイドと定義をあわせたい時、たとえば、Push通知の形式とか。運用によると思うが、たとえば、GoogleAnalyticsなどの計測の定義など
- RESTAPI以外にも活用できる部分はあると思う。Swaggerはエンドポイントとモデルを定義できる。APIで使わないならモデルの部分だけになると思う。そのような使い方は可能だと思います。
