Swagger

1. Swagger 入門
(OpenAPI Specification)
2018/5/26
JJUG CCC Spring 2018
#jjug_ccc
#ccc_g2

2. 自己紹介
• 名前：正野 勇嗣
• 所属：NTTデータ
• 経歴：M卒14年目
• 2005〜 基盤系R&D, PJ支援
• 2008〜 自動化ツールR&D
• 2011〜 AP基盤PJ支援
• 2015〜 PMO支援
• 各種Web執筆、講演活動、大学非常勤講師

3. セッション対象者
• デジタルビジネス時代を迎え、API連携へのニーズ
がこれまで以上に高まっている現在、
• API仕様を管理するOSSフレームワーク「Swagger
」(スワッガー)が大きな注目を浴びています。
• 本セッションでは、同フレームワークの未経験者・
初心者を対象に、その概要や基本的な使い方を解説
していきます。

4. Swagger?
• RESTベースのAPIのためのドキュメンテーショ
ンフレームワーク

5. インタフェース仕様書
• 呼出仕様定義を行う設計の要
API
コンシューマ
API
プロバイダ
API呼出
インタフェース
仕様書

6. Swagger Specの位置付け
• インタフェース仕様書を書くための手段
Swagger Spec
(JSON/YAML)
API
コンシューマ
API
プロバイダ
API呼出
インタフェース
仕様書

7. hello Swagger Spec
openapi: 3.0.0
info:
version: 0.0.0
title: Simple API
paths:
/:
get:
responses:
'200':
description: OK
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md

8. OpenApi Specification
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md

9. インタフェース仕様書

10. Open API Initiativeに寄贈
On Nov. 5, 2015, SmartBear in conjunction with 3Scale,
Apigee, Capital One, Google, IBM, Intuit, Microsoft,
PayPal, and Restlet announced the formation of the Open
API Initiative

11. Swagger?OAS?
• ver 2.0の時にOpenAPI Initiativeに寄贈
Version 識別子 Swagger Spec OAS
1.2 swaggerVersion ◯
2.0 swagger ◯
3.0 openapi ◯

12. インタフェース設計が重要視
されてきた背景
• マイクロサービス化（システム構造、技術トレン
ド）
• APIエコノミー化（デジタルビジネス）

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

14. Monolith AP
業務A
単一のアプリケーションで構築
モノリス(一枚岩)とマイクロサービス
Microservice AP
Microservice AP
Microservice AP
業務A
小さな粒度で分割して構築
マイクロサービスを「構造面」から理解するにはモノリス
と比較すると有効
業務B業務B
業務C
業務C

15. 環境構築 環境変更
運用・監視
障害対応
開発 ビルド デプロイ
旧来のコーディング・自動化範囲
マイクロサービス時代のコーディング・自動化範囲
Infrastructure
as Code
Infrastructure
as Code
CI/CD
Dev Ops
Spring Boot
デザパタ
クラウド
自動化技術の「開発」フェーズ以外への広が
り
https://news.mynavi.jp/itsearch/article/devsoft/1594

16. APIエコノミー
• Uberの配車ビジネスやAirbnbの民泊に代表され
るデジタルビジネスにおいても、APIエコノミー
化が進む
• Google Map APIやTwitter APIなどさまざまなAPI
を組み合わせて素早くシステムを構築

17. APIエコノミーとは
APIで繋ぐ対象を単なる「プログラム」ではなく、「システム」「ビジネス」
とすることで、素早く新たな価値を生み出す経済圏（エコノミー）を生み出
す
https://news.mynavi.jp/itsearch/article/devsoft/2182

18. Programmable Web
• Programmable Webでは、2018年3月時点で
19,000以上のAPIが検索可能で、2009年9月の10
倍、2006年5月の100倍程度に達しています。
https://www.programmableweb.com

19. 事例：Fidor Bank
• ドイツの銀行
• REST API
• http://docs.fidor.de
• 例：
• POST /sepa_credit_transfers
• Send money to another bank account through
SEPA
https://www.slideshare.net/kounan13/20170911-api-meetup-tokyo-21

20. Fidor Banking API

21. まとめると
インタフェース設計はシステム構築の要
• サービスの組合せのトレンド
• マイクロサービス化：小さなサービスが沢山
• APIエコノミー化：API（サービス）の組合せで
システム構築
• オープンAPIのトレンド
• 世の中には何万（それ以上）ものAPIが利用可能
• 金融機関など様々な企業がAPIをオープンに

22. インタフェース仕様書
• 呼出仕様定義を行う設計の要なのに
API
コンシューマ
API
プロバイダ
API呼出
インタフェース
仕様書

23. 仕様と実装の乖離
APIプロバイダとAPIコンシューマ間の悩み
1. Androidのアプリから叩いているサーバのAPIが機能追加されたた
めに、3日間かけてテストして終わったと思ったら、いつのまに
か更なる仕様変更が入っていた。
2. APIのインタフェースを定義するドキュメントの仕様に従ってア
クセスしたら、実は実装との乖離があり、うまく動かなかった。
• サービスインに影響を及ぼす重大な問題だが
• インタフェースの向こうの世界は関与できないことが多い
「常に」正しい仕様書を

24. 正しい仕様書を書かない理由
• バグフィックス（コード修正）を優先し設計書
修正は後日。そのまま修正されず。
• 仕様書と乖離しても気づく仕組みがない（テス
トコードがない）
自動化の必要性

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

26. Why Swagger?
(どこがいいの？)
• Common Language - 言語間で共通で分かりやすい
• Human/Machine Friendly - YAML/JSONで分かりやすい
• API Lifecycle - 全部入り（Design, documentation, code
generation, testing, API management, monitoring）
• Development Process Integration - contract-first approachで既存
API/新規APIにも対応
• Community Driven - OSS/400人のグループで構成
• Ever-Growing Toolset -
http://swagger.io/getting-started-with-swagger-ii-but-why/

27. Swagger関連
ツールマップ

28. 自動生成ツールによる
整合性の担保
API
コンシューマ
API
プロバイダ
API呼出
インタフェース
仕様書
(HTML)
Swagger Spec
(JSON/YAML)
Swagger UI
Swagger
Codegen
Swagger
Codegen Swagger
Core
Swagger Editor
https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md

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

30. 自動生成ツールによる
整合性の担保
API
コンシューマ
API
プロバイダ
API呼出
インタフェース
仕様書
(HTML)
Swagger Spec
(JSON/YAML)
Swagger UI
Swagger
Codegen
Swagger
Codegen Swagger
Core
Swagger Editor
https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md

31. Swagger Editor

32. 自動生成ツールによる
整合性の担保
API
コンシューマ
API
プロバイダ
API呼出
インタフェース
仕様書
(HTML)
Swagger Spec
(JSON/YAML)
Swagger UI
Swagger
Codegen
Swagger
Codegen Swagger
Core
Swagger Editor
https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md

33. Swagger UI

34. Swagger Codegen
• APIコンシューマのドライバコードやAPIプロバ
イダのスタブコードを自動生成
API
コンシューマ
API
プロバイダ
API呼出
Swagger Spec
(JSON/YAML)
Swagger
Codegen
Swagger
Codegen
スタブコードドライバコード

35. 例：ドライバコード

36. Generation Gap
パターンの適用
API
プロバイダ
（抽象クラス）
Swagger CodegenSwagger Spec
(JSON/YAML)
API
プロバイダ
（具象クラス）
継承

37. 自動生成ツールによる
整合性の担保
API
コンシューマ
API
プロバイダ
API呼出
インタフェース
仕様書
(HTML)
Swagger Spec
(JSON/YAML)
Swagger UI
Swagger
Codegen
Swagger
Codegen Swagger
Core
Swagger Editor
https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md

38. Swagger Core
@Path("/pet")
@Api(tags = {"pet"})
@Produces({"application/json", "application/xml"})
public class PetResource {
@GET
@Path("/{petId}")
@ApiOperation(value = "IDによるPetの検索”, response = Pet.class)
@ApiResponses(value = {
@ApiResponse(code = 400, message = "無効なIDの指定"),
@ApiResponse(code = 404, message = "Petは見つかりません") }
)
public Response getPetById(
@ApiParam(value = “Pet ID", required = true)
@PathParam(“petId")
Long petId) throws NotFoundException {
// 処理内容は省略。IDによるPetの検索処理
}

39. もう少し突っ込んで
学習する場合

40. 実はもっとあります
https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md
分類 ツール名
Low-Level
tooling
swagger-parser, swagger-models, KaiZen OpenAPI Parser,
openapi3-ts, swagger2openapi, odata-openapi,
microsoft.OpenApi.net, openapi3_parser, oas_parser
Editors
Apicurio Studio, KaiZen OpenAPI Editor, RepreZen API Studio,
OpenAPI-gui, SwaggerHub, swagger-editor
User
Interfaces
openapi-viewer, swagger-ui, lincoln, WebSphere Liberty
Widdershins, angular-swagger-ui
Code
Generators
baucis-openapi3, Google Gnostic, serverless-openapi-
documentation, zero-rails_openapi, slush-vertx
,WebSphere Liberty, swagger-node-codegen

41. vs SOA
SwaggerはSOAからマイクロサービスへ開発のス
タイルをシフトする流れの中で出てきた技術とも
言える
要素技術 SOA マイクロサービ
ス
通信・プロトコル SOAP REST
データ形式 XML JSON
インタフェース定義 WSDL Swagger Spec
OAS

42. 2.0 -> 3.0.0
https://openapi-converter.herokuapp.com

43. Swagger Hub
• クラウド上で管理可能

44. Swagger Inspector
• パラメータ指定等、実行に便利

45. 非機能面の集約
製品情報
API
レコメンド
API
レビュー
API
集約DB
API
API
コンシューマ
監
視
流
量
制
セ
キ
ュ
監
視
流
量
制
セ
キ
ュ
監
視
流
量
制
御
セ
キ
ュ
リ
テ
ィ
API
コンシューマ
製品情報
API
レコメンド
API
レビュー
API
集約DB
API
API
Managem
ent
監
視
流
量
制
セ
キ
ュ
API Management無し API Management有り
監
視
流量
制
セ
キ
ュ

46. API Management連携
• yamlを入力にAPI Proxy定義可能

47. まとめ
• MSA/APIエコノミーの潮流
• 仕様と実装の乖離
• インタフェース設計の重要性 -> Swagger
• Swagger 3.0.0。SwaggerHubなど更なる進化