「Swaggerを利用した新規サービス開発」というタイトルで登壇して来ました

API, Swagger, イベントレポート

この記事は最終更新日から1年以上が経過しています。

WIZYではAPI開発にSwaggerを利用しています。
採用に至った経緯と実際どのように利用しているか。
どのようなメリットがあるのかというのを紹介したいと思います。

Swagger採用に至った経緯

Swaggerに初めて出会ったのはre:Invent 2015のBootcampでした。
そのときはAPI Gateway + Lambdaでサーバレスなアーキテクトを学ぶ場だったのですが、
Swagger API Gateway Importerというものがツールとして使用されました。
これはSwagger Spec(YAML形式で書かれたAPI仕様)から自動的にAPI Gateway + Lambdaを作成してデプロイしてくれるというものです。
現在はサーバレスのフレームワークなどが出て来ていますが当時はそのようなものは無く、非常に画期的なものに思えました。

当時APIの仕様を記述する共通言語としてはRAMLとSwaggerがあったと思います(他にもあったかもしれませんが)
私はRAMLを使ったことがある程度だったのですがpublickeyの記事を見てこれからはSwaggerなのかなと思いSwaggerを使い始めました。

Swagger Spec

Swagger SpecとはSwaggerの書式で定義したAPI仕様です。
Swagger SpecはYAMLまたはJSON形式で記述されます。仕様はこちら

前述したようにこのAPI仕様はOpen API Initiativeという団体によって作成され、
OpenAPI Specificationと等しいものになります。現在の最新バージョンは2.0です。

Swagger Editorというオンラインエディタがありますので実際に触って試すことができます。
swagger_screenshot.jpg

Swagger Code Generator

Swagger SpecでAPI仕様を作成すると仕様書からドキュメントやソースコードを生成できるようになります。
Swagger Specから何かを生成する際にはSwagger Code Generatorを使用します。

何が作れるかはSwagger Code Generator(jar)を叩くと教えてくれます。
WIZYではドキュメントに html2 APIクライアントに python を使用しています。
$ java -jar swagger-codegen-cli.jar
Available languages: [android, aspnet5, async-scala, cwiki, csharp, cpprest, dart, flash, python-flask, go, groovy, java, jaxrs, jaxrs-cxf, jaxrs-resteasy, jaxrs-spec, inflector, javascript, javascript-closure-angular, jmeter, nancyfx, nodejs-server, objc, perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, sinatra, rails5, slim, spring, dynamic-html, html, html2, swagger, swagger-yaml, swift, tizen, typescript-angular2, typescript-angular, typescript-node, typescript-fetch, akka-scala, CsharpDotNet2, clojure, haskell, lumen, go-server]

WIZYのAPIファーストな開発手法

  1. 機能要件に従ってテーブル定義等の仕様を決める
  2. フロントの要件に従ってAPI仕様をSwagger Specで書く
  3. Swagger Specに従ってAPIを実装
  4. Swagger Code Generatorでクライアントを生成
  5. 生成したクライアントを使用してフロントのアプリを実装

3と4,5は並行で実施可能です。

Swaggerを導入するメリット

  1. API仕様がYAMLの差分でレビュー可能。そしてそのままコードとなる
    API仕様をExcelなどで管理する場合と比べた場合。まずテキスト形式のため差分を簡単に比較できます。
    変更履歴が正しく更新されなかったり言葉が曖昧である場合もありますがSwagger Specの場合は曖昧さがありません。
    そして、Swagger Specからそのままソースコードを生成できるため実装漏れや仕様書とソースの乖離がありません。
    Swagger SpecはJSON形式でも書くことができますが、
    JSONではなくYAMLをオススメするのはYAMLの場合は自由に改行/インデントができないため人によって
    JSONの場合に発生するスペース入れる入れない問題や複数行を1行にまとめたりといった書き方の違いというのが起こりません。
    これが起きると同じ仕様でも書き方の違いによって差分が発生してしまいどこを変更したかが分かりにくくなります。

  2. 仕様がバージョン管理されるため安心してWeb/APIのリリースが可能
    Swagger SpecはGitなどのバージョン管理を利用してリリースを管理することができます。
    WIZYではSwagger SpecとCode Generatorで生成したpythonクライアントを同じリポジトリで管理していて、
    APIの仕様を変更する毎にリリース(タグ)を作成します。
    API仕様とAPIの実装が正しくバージョン管理されることでフロントとAPIのリリースを分離して実施しやすくなります。
    なぜならSwagger Specに変更がない場合APIのインタフェース仕様が変更されないことが約束されるため
    前のバージョンとインタフェースに互換性があることが分かるからです。
    UIを変更しただけの場合やSQLをチューニングしただけの場合など前のバージョンと内部のロジックに
    互換性がある場合は並行稼働しても問題ない事も分かります。

Swaggerの仕様バージョンについて

Apigeeの方(Swaggerの中の人)曰く。Code Generator言語によって品質がまちまちであり。
Swaggerの3.0にて互換性のない変更が入る予定があるので正式採用は3.0が出てからの方が良いかもしれません。

3.0は2.0から互換性のない修正が入ると言われていますが、Swaggerという名前を使っているところを消すので
そういう風に言っているらしく、現状2.0を使用していても移行にあまり問題はなさそうです。
(仕様もちょいちょい出てますが多分大丈夫そうです。。)

まとめ

Swaggerを使用する事でAPI開発を快適に行うことができるようになりますが、
使うだけで良いAPIが作れるというものではないのでAPI設計については別途学ぶ必要があります。
API設計についてはこれといった正解がない場合がよくあるので、
Swagger Spec上で議論しながら検討を行うのが良いかなと思います。

この内容で先日API Meetupで登壇して来ました。

懇親会でお話しさせていただいた方からは大変参考になったとか実際使って見たいと
仰っていましたので、少しは普及の助けになったのかなと思います。

Swaggerそのものは以前からあるものですがまだまだ参考になる文献が少ないので、
Swaggerの利用が当たり前になりSpecについてのプラクティスが増えると面白いかなと思います。

API, Swagger, イベントレポート