Swaggerとは

【連載】

Swagger入門 - 初めてのAPI仕様管理講座

【第1回】Swaggerとは

[2017/02/07 08:30]正野 勇嗣 ブックマーク ブックマーク

  • 開発ソフトウェア

開発ソフトウェア

デジタルビジネス時代を迎え、API連携へのニーズがこれまで以上に高まっている現在、API仕様を管理するOSSフレームワーク「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について正しく記述した仕様書が必要となってきます。

APIのインタフェース仕様書の位置付け

Swaggerとは

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

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

swagger.io公式サイト

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のスタブを自動生成

Swaggerツール群の関係性

以前からのサービス間連携手法と対比すると、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 Editorでminimal.yamlをオープン

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

Swagger Editorの画面構成

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

minimal.yaml準拠のAPIの実行結果

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エコノミーの作り方」をご参照ください。

著者紹介


正野 勇嗣 (SHONO Yuji ) - NTTデータ シニア・エキスパート

2011年頃まで開発自動化技術のR&Dに従事。その後、開発プロジェクト支援やトラブルシューティング等に主戦場を移す。「ソースコード自動生成」に加えて、JenkinsやMaven等の「ビルド自動化」、JsTestDriverやSelenium等の「テスト自動化」を扱うようになり、多様化する開発自動化技術動向に興味。

最近は第四の自動化であるInfrastructure as Code等の「基盤自動化」の魅力に惹かれている。開発自動化技術に関する雑誌・記事執筆も行う。2児のパパ。

※ 本記事は掲載時点の情報であり、最新のものとは異なる場合がございます。予めご了承ください。

関連リンク

2395
2
【連載】Swagger入門 - 初めてのAPI仕様管理講座 [1] Swaggerとは
今、API仕様を管理するOSSフレームワーク「Swagger」(スワッガー)が大きな注目を浴びています。Microfsoft、Googleらが推進する同フレームワークはどういったものなのか。その概要や基本的な使い方を解説していきます。
https://news.mynavi.jp/itsearch/2017/02/06/swagger/swaggerrec.jpg
今、API仕様を管理するOSSフレームワーク「Swagger」(スワッガー)が大きな注目を浴びています。Microfsoft、Googleらが推進する同フレームワークはどういったものなのか。その概要や基本的な使い方を解説していきます。

会員新規登録

初めてご利用の方はこちら

会員登録(無料)

一覧はこちら

今注目のIT用語の意味を事典でチェック!

一覧はこちら

ページの先頭に戻る