Swaggerのさらなる活用

Swagger SpecのインポートによるAPI Proxyの作成

OAuthを使った認可や、過負荷時の流量制御など、APIの非機能部分の担保は重要な要素となっています。

ただ、各APIで担保すると、作業負荷が高く、方式の統一が困難です。APIエコノミーが進展する状況においては、APIを束ねて管理する存在が求められます。近年、API Gatewayデザインパターンにより、APIを集中的に管理する方式がベストプラクティスとなっています。

また、Swaggerを使ってAPIインタフェース仕様書やAPI単体を作っていくだけでなく、API Gatewayパターンの構築にも活用することができます。例として今回、Swagger Specをインポートし、Google傘下のApigeeが提供するAPI Gatewayである「API Proxy」を作成します。なお、類似製品としては、AWS API Gateway Importerなどがあります。

ブラウザから「https://apigee.com/」にアクセスし、「SIGN UP FREE」をクリックし、アカウントを作成します。

メールアドレスやユーザ名などを入力し、「Create account」をクリックします。

確認メールが届くので、アクティベーションリンクをクリックします。

アカウントが作成できたら、トップ画面にて「SIGN IN」をクリックし、ログイン画面にアクセスします。ユーザIDとパスワードを入力し、「SIGN IN」をクリックします。

管理画面が表示されます。次に「API Proxies」をクリックします。

「+Proxy」をクリックし、API Proxyを追加します。

「Use OpenAPI」をクリックし、Swagger Specを読みこみます。

第一回で紹介したSwagger Editorにてサンプル提供されているecho.yamlをインポートします。「Upload file」タブにて、Swagger Specファイル(echo.yaml)をドラッグ&ドロップし、「Select」をクリックします。

echo.yamlの読み込み設定されたことを確認したら、「Next」をクリックします。

Swagger Specの内容を元に、以下の「Proxy Name」「Proxy Base Path」「Existing API」「Description」といった項目が入力済みであることがわかります。「Next」をクリックします。

そのまま「Next」をクリックします。

「Authorization」に「Pass Through (none)」を設定し、「Next」をクリックします。

設定を確認し、「Next」をクリックします。

「Deploy Environments」に「test」を設定し、「Build and Deploy」をクリックします。

以下の通り、エラーなく終了したことを確認します。「Echo」APIのリンクをクリックします。

APIが作成されていることがわかります。

curlにてAPI Proxyにアクセスすると、API Proxy経由で「http://mazimi-prod.apigee.net/」にアクセスされていることがわかります。

$ curl http://xxxxxx-test.apigee.net/echo
GET
http://mazimi-prod.apigee.net/
Headers:
{
    "accept": "*/*",
    "host": "mazimi-prod.apigee.net",
    "user-agent": "curl/7.51.0",
    "x-forwarded-for": "123.12.1.234, 221.21.1.212",
    "x-forwarded-port": "80",
    "x-forwarded-proto": "http"
}

CIへの組み込み

「コーディングやユニットテストが完了したら、Eclipseのエクスポート機能でwarファイルを作成するが、いつもエクスポートしているライブラリ管理担当者が離任したら本番環境用のアプリケーションのビルドの方法がわからなくなった」――ドキッとする方もいらっしゃるのではないでしょうか。

ソースコード自動生成やテスト自動化だけでなく「ビルド・デプロイ自動化」は、近年では当たり前のようになってきました。なかでも、CI(Continuous Integration：継続的インテグレーション)はアプリケーションのビルドプロセスを継続的に自動化し、結果を可視化します。代表的なツールはJenkins、Concourse CI、Travis CIなどです。

4つの自動化領域とCI

No	領域名	対象フェーズ	利用技術例
1	ソースコード自動生成	開発(設計・実装)	Eclipse, TERASOLUNA ViSC
2	テスト自動化	開発(テスト)	JUnit, JsTestDriver, Selenium, Selenide
3	ビルド・デプロイ自動化(DevOps, CI/CD)	ビルド・デプロイメント	Jenkins, Gradle, Maven
4	基盤自動化(Infrastructure as Code)	環境構築・環境変更	構築:SDN, Chef, Puppet テスト:ServerSpec 概念:Immutable Infrastructure 仮想化:Docker

少しずつ自動化の領域を広げ、運用担当者やライブラリ管理担当者の負荷を下げようという取り組みの性質上、CIは、継続的な「カイゼン」を実施する文化と非常によくマッチします。通常は、アプリケーションのコンパイル、ユニットテストの実行や、APサーバへの自動デプロイが主にカバーされている領域でしょう。

A/Bテスト、カナリアリリース、ブルーグリーンデプロイなど、デプロイを行う手段としてもさまざま存在し、CIがカバーする領域が広がってきています。さらには、基盤自動化技術と組み合わせて、急な高負荷に応じてアプリケーションが動作する環境をスケールさせるなど、より高度なビルド・デプロイを実現するケースもあります。

ここまでSwaggerの記事をお読みになってこられたみなさまは、コードの領域だけでなく、ドキュメンテーションの領域まで広げられるのでは? と考えられた方もいらっしゃるのではないでしょうか。Concourse CIなどのツールを使えば、お使いのCI環境におけるビルドパイプラインと呼ばれる一連のCIの処理の流れに簡単に組み込むことができ、コードとドキュメントの整合性を保ちやすくなります。YAMLで記載されたSwagger Specのバリデーションや、Swagger UIの自動公開などを組み込んでみると良いでしょう。

連載を振り返って

APIエコノミーがより広がりを見せ、クラウドやマイクロサービスが進展する状況においては、さまざまなAPIの利用を前提とするため、Swaggerのようなドキュメント化技術の重要性は高まっています。

SwaggerはSwagger Specを中核とし、Swagger UI/Swagger Codegen/Swagger Coreといったツール群で構成されることを説明しました。もちろん、Swagger単体で開発ができるわけではないので、Apigeeのようなクラウドを前提としたAPI Managementツールを利用したり、CIへ組み込んだりするなど、システム開発全体を見渡して検討する必要があるでしょう。

Swaggerは2015年12月31日に米Microsoftや米Googleなどにより設立されたOpen API Initiativeに寄贈され、OAS(OpenAPI Specificaion)とも呼ばれます。現在、Swagger(OAS) 3.0の策定が進められており 、今後さらなる機能改善が図られていく見込みです。2017年2月28日にドラフト版の位置付けで3.0.0-rc0が公開され、5月8日現在は3.0.0-rc2の仕様がGitHubに掲載されています。

著名な企業にも注目されており、今後も進化を続けるSwaggerをご担当するプロジェクトにて、ぜひ試してみてください。