Swaggerで始めるAPI定義管理とコードジェネレート | iOSDC 2017 前夜祭

twitter.com

REST APIインターフェイス仕様をSwaggerのAPIドキュメントで一元的に定義・管理することで、モバイルとサーバエンジニア間のコミュニケーションを齟齬なく円滑に進めることができます。

さらに、SwaggerのSwiftコードのジェネレート機能を活用することで、工数の削減と品質の向上を図り生産性を高める方法をご紹介します。

Swaggerで始めるAPI定義管理とコードジェネレート

f:id:niwatako:20170915184547j:plain

f:id:niwatako:20170915184614j:plain

4 月からフリーランスです。

f:id:niwatako:20170915184635j:plain

サーバーの方とコラボレーションしながら開発していると思いますが、思っているものと違うものが入ってくることがあると思う。

齟齬をなくして、円滑にすすめるために重要かと思う。値の方がJSONからはわからないとか、本番ではNULLがはいってきたとか。そうしたことを定義することで手戻りが少なくなる

f:id:niwatako:20170915184646j:plain

大手が立ち上げた規格化?プロジェクトで採用されている

f:id:niwatako:20170915184758j:plain

このような定義内容があります。

f:id:niwatako:20170915184824j:plain

専用エディタが提供されていてブラウザで動きます。Specファイルからドキュメントをジェネレイトして見られるようにしたり、モックサーバーを作ることができます。

エディタです。

f:id:niwatako:20170915184920j:plain

ローカルでも動きます。右手が、定義が可視化されたものです。

左に定義がSwagger SpecとしてYAMLで書かれています。

Path=EndpointとDefinition=JSONのモデル定義です。

定義を間違えるとすぐ分かる

f:id:niwatako:20170915185016j:plain

Getエンドポイントを定義してみます。

f:id:niwatako:20170915185034j:plain

Arrayだとか、requireで必須だとか定義できる。

レスポンスは200と400で定義して、それぞれどのような内容が返るかを定義できる。

モデル定義。左に定義すると右に可視化されている。モデル定義の入れ子も可能。Int32とInt64を分けることが出来る。Statusのようなものはenumで定義できる。

f:id:niwatako:20170915185159j:plain

exampleを定義しておくと、モックサーバーがその値を返す。何も定義しなければその型のデフォルト値が返る。

f:id:niwatako:20170915185323j:plain

モックサーバーができて、APIサーバーが完成していなくてもクライアントを開発できるし、仕様に齟齬がない。

f:id:niwatako:20170915185359j:plain

コードジェネレート出来る。なぜコードジェネレートしたいか。折角定義したのに人間が実装する時に間違えたら勿体無い

f:id:niwatako:20170915185415j:plain

Swagger Codegen 様々な言語に対応している。Kotlinも5月ぐらいに対応。新しい言語にも積極的に対応している

f:id:niwatako:20170915185505j:plain

f:id:niwatako:20170915185519j:plain

Swiftの場合

f:id:niwatako:20170915185555j:plain

実行方法

f:id:niwatako:20170915185621j:plain

Podのバージョンをインクリメント出来ると便利

どんなオプションが有るかはこちらで確認

f:id:niwatako:20170915185655j:plain

リクエスト部のAPIと、モデル、通信用クラスなどがGenerateされる。

f:id:niwatako:20170915185709j:plain

f:id:niwatako:20170915185739j:plain

f:id:niwatako:20170915185747j:plain

Cadableに準拠したモデルができました。requireでないところはOptionalになります。

f:id:niwatako:20170915185754j:plain

通信部分はSuccessかErrorかのコールバックが基本です。

f:id:niwatako:20170915185829j:plain

リクエスト部分は柔軟にカスタマイズできます

f:id:niwatako:20170915185856j:plain

f:id:niwatako:20170915185916j:plain

f:id:niwatako:20170915185922j:plain

f:id:niwatako:20170915185937j:plain

f:id:niwatako:20170915185941j:plain

f:id:niwatako:20170915185950j:plain

f:id:niwatako:20170915190000j:plain

f:id:niwatako:20170915190012j:plain

MultifileSwaggerというのを作っている人がいる

f:id:niwatako:20170915190039j:plain

f:id:niwatako:20170915190045j:plain

タグを打ってCocoaPodsをタグのバージョンに合わせるように徹底する

f:id:niwatako:20170915190108j:plain

f:id:niwatako:20170915190114j:plain

成熟してきている中で、ノウハウも溜まってきている。開発効率や品質向上がフォーカスされていくのではないか。そうした中でAPI定義やコードジェネレートが一助になれば

QA

  • 既にSwaggerで作られたわけではないサーバーがあるとして、別に定義を用意するという使い方もあるでしょうか
    • 両サイドの認識合わせに定義を明示することは意味があるのではないかと思います。ジェネレートしたコードにリプレースする意味があるか。うまく入れ替えられるなら良いと思う。インターフェースさえうまく導入できそうであれば活用できると思う
  • 定義を書き出したがサーバーが準拠していない場合
    • 曖昧だったところとの不整合が起きてクラッシュが起きる可能性はあるが、それはその曖昧な運用だったということだと思うので、リリースまでに修正できるなら、より品質の高い状態でリリースでき、今後の運用もしやすくなると思います。
  • API以外とかで使えますか、たとえば、定数や型などでやりたい時にAPI以外に、アプリ側と他のサーバーサイドと定義をあわせたい時、たとえば、Push通知の形式とか。運用によると思うが、たとえば、GoogleAnalyticsなどの計測の定義など
    • RESTAPI以外にも活用できる部分はあると思う。Swaggerはエンドポイントとモデルを定義できる。APIで使わないならモデルの部分だけになると思う。そのような使い方は可能だと思います。