Swaggerとは

仕様と実装の乖離が許されないAPI

システム開発のトレンドとして、マイクロサービス化が進んできています。モノリス(一枚岩)スタイルの開発に比べて、アプリケーションの単位は小さくなり、多くのサービスが構築されます。

Uberの配車ビジネスやAirbnbの民泊に代表されるデジタルビジネスにおいても、APIエコノミー化が進んできており、Google Map APIやTwitter APIなどさまざまなAPIを組み合わせて素早くシステムを構築します。
Programmable Webでは、2017年1月時点で16,590以上のAPIが検索可能で、2009年9月の10倍以上、2006年5月の90倍近くに達しています。

では、そういったマイクロサービス・APIエコノミーの開発現場では、一体どのようなことが起こっているのでしょうか。

例えば、Androidのアプリから叩いているサーバのAPIが機能追加されたために、3日間かけてテストして終わったと思ったら、いつのまにか更なる仕様変更が入っていた。APIのインタフェースを定義するドキュメントの仕様に従ってアクセスしたら、実は実装との乖離があり、うまく動かなかった。

このようにAPIプロバイダとAPIコンシューマ間の悩みはさまざまです。ただし、いずれもサービスインに影響を及ぼす重大な問題と言えます。インタフェースの向こうの世界は関与できないことが多いだけに、仕様と実装の乖離はあってはならないものなのです。

APIエコノミーを作るにあたり、このようなことを起こさないためにも、APIについて正しく記述した仕様書が必要となってきます。

Swaggerとは

Swaggerはこうした課題に対する解決のアプローチを提供します。

SwaggerはOAI(Open API Initiative)が採用しているREST APIを構築するためのオープンソースのフレームワークです。OAIは、2015年11月にマイクロソフトやグーグルなどによって結成され、Swaggerを用いてAPIの標準化を推し進めています。

Swaggerの実体はYAMLやJSON形式で定義されるドキュメント仕様のSwagger Specと、以下のツール群から構成されます。表中の下線に示すSwagger Spec(Swagger仕様)こそがSwaggerの中核をなすものになります。

表 : Swaggerツール群

ツール名	説明
Swagger Core	API実装コードからSwagger Specで記載された設計を自動生成
Swagger Editor	Swagger Specの設計書を記載するためのエディタ
Swagger UI	Swagger Specで記載された設計からドキュメントを自動生成
Swagger Codegen	Swagger Specで記載された設計からAPIのスタブを自動生成

以前からのサービス間連携手法と対比すると、SOAにおけるWSDLにあたるのがSwagger Specです。SwaggerはSOAからマイクロサービスへ開発のスタイルをシフトする流れの中で出てきた技術とも言えます。

表 : SOAとマイクロサービスの対比におけるSwagger Specの位置付け

要素技術	SOA	マイクロサービス
通信・プロトコル	SOAP	REST
データ形式	XML	JSON
インタフェース定義	WSDL	Swagger Spec

Swagger Editorを使ってまずは動かしてみる

Swagger Specの理解のために最もお手軽なのが、インストール不要でブラウザベースで使用可能なSwagger Editorを使ってみることです。ブラウザで「http://editor.swagger.io/」にアクセスし、[File]-[Open Example]をクリックします。[Pick one of the examples]にて[minimal.yaml]を選択し、[Open]をクリックします。

以下の画面が表示されます。左側のペインがエディタとなっています。Swagger仕様に準拠したYAML形式で記載されており、修正すると、右側のペインと同期されます。右側のペインにおいて、[Try this operation]をクリックすることで、APIを試すことができます。

下図の[Send Request]をクリックすることで、APIを実行でき、[Response]に結果が表示されます。

Swagger Specのサンプル

Swagger SpecはREST APIを構築するためのJSON形式もしくはYAML形式で書かれたドキュメントです。前節で動作させたYAML形式の例は以下の通りです。

---
swagger: '2.0'
info:
  version: 0.0.0
  title: Simple API
paths:
  /:
    get:
      responses:
        200:
          description: OK

また、JSON形式でも記述することができ、以下の通りになります。Swagger Editorの[File]-[Download JSON]から、ダウンロード可能です。

{
    "swagger": "2.0",
    "info": {
        "version": "0.0.0",
        "title": "Simple API"
    },
    "paths": {
        "/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    }
}

上記の例では、swaggerのバージョンは2.0を使用しており、Simple APIという名前のAPIのバージョンは0.0.0です。URL定義したパスは[/]のみであり、[http://localhost/]といった形でリソース直下のURLにGETアクセス可能です。この例は極めてシンプルな例ですので、パラメータはなく、ステータスコードとして200を返します。

*　　*　　*

マイクロサービスやAPIエコノミーが進展する状況においては、SwaggerのようなAPI間のインタフェース仕様管理ツールの存在の重要性は増すばかりです。次回は、Swagger UIを使うとどういった形でAPIプロバイダとAPIコンシューマ間で共有可能なドキュメントが構築できるかを説明します。

また、システムを構築するにあたっては障害を他のAPIに波及させないCircuit Breakerや、OAuthによるセキュリティの担保といった非機能面の考慮も必要になってきます。APIエコノミーに関して詳細は拙著「APIエコノミーの作り方」をご参照ください。