前人未踏の領域へ アプリ開発編

Android, iOSアプリ開発に関する調査メモ置き場。ほとんどAndroid。はてなダイアリーから移行したため古い記事にはアプリ以外も含まれます。

Swaggerについて学ぶ(基礎知識編)

Swaggerとは

Swaggerは言語に依存しないREST APIのインターフェース仕様とそのツール群を指す。
Swaggerの仕様に沿ってAPIを定義することで、人間が理解可能で、コンピューターにも解析可能なAPI仕様書となる。

http://swagger.io/getting-started/

Swaggerの提供するもの

項目 概要
Swagger Specification JSON or YAMLによるAPI記述フォーマット。バージョン、パラメータ、型、レスポンス、必須有無、対応メソッドなどの記述ルールが定義されている
Swagger UI 記述したAPI仕様を読みやすいHTMLで確認
Swagger Editor ブラウザで利用可能な専用エディタでプレビューしながら編集
Swagger CodeGen APIを元にサーバー、クライアント双方のAPIアクセスコードを自動生成
その他 他にも多分ある

Swaggerを使うメリット

  • 決まったルールに従ってAPIを設計できる
  • 0からAPIの記述ルールを決めなくていい
  • ビューワーもついてくるので参照、エンジニア間で共有しやすい。
  • テキストファイルなのでGithubなどでバージョン管理ができる
  • パーサーがあるので、その気になれば他のドキュメント(Wiki, Markdown

, Excel)にも変換が可能である(はず)。

  • コードもその気になれば生成できる(ベストなものとは限らないと思うけど)

競合の存在

同様のAPI標準化ではAPI BluePrintなどいくつかの競合が存在するが、Googleなども参加するOpen API Initiativeで基準APIフォーマットとして採択された点は将来性の面で強みとなるだろう。とはいえユーザーが選んだものがデファクトとして勝利するので、個人で使うなら自分に馴染むものを選ぶ、でいいと思う。

どこから始めるか

  • トップダウンアプローチ:これからAPIを書く場合、Swagger Editorを使ってAPIを書き、アクセスコードを自動生成するのがよい
  • ボトムアップアプローチ:既存のコードがある場合、Swagger Editorを使って APIを手書きするか、JAX-RXを使っていればSwaggerフォーマットのテキストを自動生成できる。

まとめ

ライブラリ含め、どちらかというとJavaよりなんだけど、
API仕様自体はJavaに依存していないし、各種言語向けのコードも書き出せるので気にしなくてもいいんじゃないかと思う。
とりあえずWikiとかに適当で統一感もなく保守もされないされないようなドキュメント書いてるくらいなら
swagger仕様に合わせて仕様書作っておいて、gitでコード管理すると良いかと思う。