SlideShare a Scribd company logo
1 of 33
Download to read offline
Copyright©2018 NTT corp. All Rights Reserved.
Spring I/O 2018 報告会
2018年7月30日
NTTソフトウェアイノベーションセンタ
岩塚 卓弥
2Copyright©2018 NTT corp. All Rights Reserved.
• 名前:岩塚 卓弥
• 所属:NTT ソフトウェアイノベーションセンタ
• NTTの研究所のうちソフトウェアを専門に扱う
• 自部署ではソフトウェア工学を研究
• Springベースのグループ共通フレームワークの整備を担当
• Spring I/O は今年で4回目
• レポートも書きました(共著)
• https://codezine.jp/article/detail/10930
自己紹介
3Copyright©2018 NTT corp. All Rights Reserved.
• Documenting RESTful APIs with Spring REST
Docs and RAML
• スライド:
https://speakerdeck.com/mduesterhoeft/documenting-
restful-apis-with-spring-rest-docs-and-raml
• 動画:
https://www.youtube.com/watch?v=VwKc34W96Cw&li
st=PLe6FX2SlkJdRCNFdhWgpRmJybXafo-Uqk&index=20
• Consumer driven contracts in a polyglot world
• スライド:
https://docs.google.com/presentation/d/19BFGJiTElU3
VVIbpF3Gqac26m4uaNpPEQpVB1eIPa90/edit#slide=id.
p
• 動画:
https://www.youtube.com/watch?v=sKlwNJeQMV4&list
=PLe6FX2SlkJdRCNFdhWgpRmJybXafo-Uqk&index=25
今日のトピック
4Copyright©2018 NTT corp. All Rights Reserved.
REST Docs (and RAML)のセッションのQ&Aで
Spring Cloud Contract との関連を問う質問があった
→ セッションの内容とはコンテキストが違い,要領を得ず
キーワードレベル(API, テスト)で共通しているため,
うまく整理できていない人が多いのかも…
きっかけ
5Copyright©2018 NTT corp. All Rights Reserved.
RESTful API 開発
6Copyright©2018 NTT corp. All Rights Reserved.
用途による分類
Public API Internal API
App
API
3rd party App 3rd party App
3rd party App
• 誰がどう使うかわからない
• API変更時に利用側の合意は不要
• そもそも全員の合意は取れない
• 外部の開発者に使ってもらうための
諸々を用意する必要がある
• 使う人・使用方法がわかっている
• API変更時に利用側の合意が必要
• 勝手に変えると他のサービスが
壊れる場合がある
• 内部の開発者が使えればよい
App
API
App
App
AppAPI API
API
7Copyright©2018 NTT corp. All Rights Reserved.
使えない / 使いたくない API
• そもそも欲しい機能がAPI化されていない
• ドキュメントがない
• ドキュメントが古い
• ドキュメントがわかりにくい
合体技
わかりにくいドキュメントをくまなく調べた結果
欲しい機能がAPIとして提供されていないことがわかる
使ってもらうためにドキュメントは必須
特に Public API の場合は充実したドキュメントがあるとよい
APIドキュメントの必要性
8Copyright©2018 NTT corp. All Rights Reserved.
多くの開発者の共通認識
• メンテナンスされたドキュメントは重要である
• ドキュメントのメンテナンスは面倒である
ドキュメントのメンテナンス
なんらかの方法でドキュメントが勝手に実装に追従してくれると嬉しい
→ いくつかのアプローチがあるが,いずれにせよ何らかの妥協が必要
9Copyright©2018 NTT corp. All Rights Reserved.
機械可読の仕様から実装もドキュメントも生成
API仕様からの生成
Spec
本当に仕様から吐き出されるソースコードと付き合っていけるか?
→ できないと結局ドキュメントのメンテナンス面倒問題と同じ構図に
記法は様々
・OpenAPI
・RAML
・API Blueprint
・...
ツールによって用途も様々
ドキュメント
ソースコード
スタブ(モック)サーバ
...
10Copyright©2018 NTT corp. All Rights Reserved.
実装そのものからドキュメントを生成
一般に,ソースコードだけでは情報が足りないので補完が必要
ソースコードからの生成
e.g. Springfox
• 実装方法に依存する
• ソースコードが読みづらくなる
• 実装内容と補完情報が乖離していないことは保証されない
11Copyright©2018 NTT corp. All Rights Reserved.
APIのテストコードからドキュメントの一部を生成
• API実装側の実装方法に依存しない
• テストされた確実な内容を出力
• デフォルトでは Asciidoctor のスニペットとして出力
• テストが失敗した場合は出力しない
Spring REST Docs
...
12Copyright©2018 NTT corp. All Rights Reserved.
Spring REST Docs ドキュメント例
生成したスニペットをincludeしてドキュメントを作成
13Copyright©2018 NTT corp. All Rights Reserved.
Spring REST Docs
• テストを利用した正確な出力 😊
• Asciidoctor (or Markdown) のスニペットを出力 😐
• ドキュメントが静的かつ簡素
• 用途が限定的
Spring REST Docs RAML Integration
• RAML形式の出力をサポートしたサードパーティ拡張
• https://github.com/ePages-de/restdocs-raml
• 実装との乖離を防ぎつつ RAML のエコシステムを活用
Spring REST Docs の拡張
14Copyright©2018 NTT corp. All Rights Reserved.
restdoc-raml の入力例
Spring REST Docs を拡張
15Copyright©2018 NTT corp. All Rights Reserved.
restdoc-raml の出力例
RAML
JsonSchema
リクエスト例
16Copyright©2018 NTT corp. All Rights Reserved.
RAMLの活用(raml2html)
17Copyright©2018 NTT corp. All Rights Reserved.
RAMLの活用(raml2html)
18Copyright©2018 NTT corp. All Rights Reserved.
RAMLの活用 (API console)
19Copyright©2018 NTT corp. All Rights Reserved.
RAMLの活用 (API console)
20Copyright©2018 NTT corp. All Rights Reserved.
Documenting RESTful APIs with Spring REST Docs
and RAML
• Public API を使ってもらうためにドキュメントが必要
• テストから生成する Spring REST Docs のアプローチを採用
• Asciidoctor の静的なドキュメントでは物足りない
→ テストから RAML を生成する拡張を作った
RAMLのエコシステムを活用できるようになった
- 動的なドキュメント
- ブラウザで動作するクライアント
- スタブ(モック)サーバの作成
- …
ここまでのまとめ
21Copyright©2018 NTT corp. All Rights Reserved.
【再掲】用途による分類
Public API Internal API
App
API
3rd party App 3rd party App
3rd party App
• 誰がどう使うかわからない
• API変更時に利用側の合意は不要
• そもそも全員の合意は取れない
• 外部の開発者に使ってもらうための
諸々を用意する必要がある
• 使う人も使われ方もわかっている
• API変更時に利用側の合意が必要
• 勝手に変えると他のサービスが
壊れる場合がある
• 内部の開発者が使えればよい
App
API
App
App
AppAPI API
API
22Copyright©2018 NTT corp. All Rights Reserved.
Consumer-driven Contracts (CdC)
App API
App
App
App
提供者 (Provider)
利用者 (Consumer)Contract
Contract
• API提供者と利用者のリクエスト/レスポンスに関する取り決め
• 各利用者はAPIのレスポンスのすべてを使いたいとは限らない
• 利用者の必要な部分だけの取り決め = Consumer Contract
• 提供者は各利用者との Contract に合意し,これを守る
Contract を前提とすることで対向をスタブ化したテストが可能になる
23Copyright©2018 NTT corp. All Rights Reserved.
Spring Cloud Contract – Contractの記述
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
Groovy DSL または YAML で記述
24Copyright©2018 NTT corp. All Rights Reserved.
Spring Cloud Contract – Providerのテスト
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
テストテストテスト テストコードの生成
リクエストに対して
Contractの通りレスポンスするか
25Copyright©2018 NTT corp. All Rights Reserved.
Spring Cloud Contract – テスト用スタブ
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
スタブ
スタブを生成
実体は jar ファイル
Contract に対応した
WireMock用のjsonが
入っている
26Copyright©2018 NTT corp. All Rights Reserved.
Spring Cloud Contract – Consumerのテスト
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
スタブ
スタブを利用してテスト
使用するスタブを指定
27Copyright©2018 NTT corp. All Rights Reserved.
Microservices ではJVM言語以外も自然に混在しえる
→ Java, maven に依存しないやり方が必要
Spring Cloud Contract の Polyglot 対応
• Contract の記述
→ Groovy DSL 以外に YAML でも記述可能
• Provider のテストコードの生成
→ Docker でテスト生成&実行
• Consumer テスト用のスタブ生成
→ Docker でスタブ生成&実行
Polyglot 対応
28Copyright©2018 NTT corp. All Rights Reserved.
Polyglot 対応 – Contractの記述
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
YAML で記述
29Copyright©2018 NTT corp. All Rights Reserved.
Polyglot 対応 – Providerのテスト
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
テストテストテスト
生成
起動しておく マウント
spring-cloud-contract
Providerにリクエストして
レスポンスを検証
30Copyright©2018 NTT corp. All Rights Reserved.
Polyglot 対応 – テスト用スタブ
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
スタブ
生成
Artifactoryへpublishされる
31Copyright©2018 NTT corp. All Rights Reserved.
Polyglot 対応 – Consumerのテスト
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
スタブ
spring-cloud-contract-stub-runner
Artifactoryから
取得して起動
テストのリクエストに
レスポンスを返す
32Copyright©2018 NTT corp. All Rights Reserved.
REST Docs を利用すると以下が可能
• テストコードからのスタブ生成
• テストコードからのContract生成
→ 既にSpring MVCのテストがあるプロジェクトで,
Spring Cloud Contract を新しく導入するときに便利
Spring Cloud Contract + REST Docs
33Copyright©2018 NTT corp. All Rights Reserved.
• Documenting RESTful APIs with Spring REST
Docs and RAML
• 実装と対応したドキュメントを作成するにはテストをソースに
するとよい
• Spring RESTDocs のコンセプトはそのままにRAMLのエコシ
ステムを利用できる拡張を作った
• Consumer driven contracts in a polyglot world
• 内部APIの連携の試験にはCdCが便利
• Spring Cloud Contract は非JVM環境にも対応
• 目的に沿った技術を使う
• キーワードだけで捉えると見誤る
• ツールに振り回されないようにコンテキストを整理すること
まとめ

More Related Content

What's hot

SQLiteDatabaseを無理矢理覗く
SQLiteDatabaseを無理矢理覗くSQLiteDatabaseを無理矢理覗く
SQLiteDatabaseを無理矢理覗くTakao Sumitomo
 
私たち企業がアクセシビリティに取り組む理由(2018年) #accfes
私たち企業がアクセシビリティに取り組む理由(2018年) #accfes私たち企業がアクセシビリティに取り組む理由(2018年) #accfes
私たち企業がアクセシビリティに取り組む理由(2018年) #accfesYahoo!デベロッパーネットワーク
 
Hint of“Passcode Lock”Screen and Logic (with LocalAuthentication).
Hint of“Passcode Lock”Screen and Logic (with LocalAuthentication).Hint of“Passcode Lock”Screen and Logic (with LocalAuthentication).
Hint of“Passcode Lock”Screen and Logic (with LocalAuthentication).Fumiya Sakai
 
Intro to OMA GotAPI Open-Source Implementation Supporting Web - Healthcare Us...
Intro to OMA GotAPI Open-Source Implementation Supporting Web - Healthcare Us...Intro to OMA GotAPI Open-Source Implementation Supporting Web - Healthcare Us...
Intro to OMA GotAPI Open-Source Implementation Supporting Web - Healthcare Us...Device WebAPI Consortium
 
MozOpenHardプロジェクトと そのコア技術について
MozOpenHardプロジェクトと そのコア技術についてMozOpenHardプロジェクトと そのコア技術について
MozOpenHardプロジェクトと そのコア技術について Takagi Koichi
 
DevRel Meetup27 Igarashi-pub
DevRel Meetup27 Igarashi-pubDevRel Meetup27 Igarashi-pub
DevRel Meetup27 Igarashi-pubTomohiro Igarashi
 
インテル Real Sense Hands On Lab
インテル Real Sense Hands On Labインテル Real Sense Hands On Lab
インテル Real Sense Hands On LabKaoru NAKAMURA
 
OMA GotAPI 標準化作業状況アップデート
OMA GotAPI 標準化作業状況アップデートOMA GotAPI 標準化作業状況アップデート
OMA GotAPI 標準化作業状況アップデートDevice WebAPI Consortium
 
DeviceConnect向けCordovaプラグインを作ってみた
DeviceConnect向けCordovaプラグインを作ってみたDeviceConnect向けCordovaプラグインを作ってみた
DeviceConnect向けCordovaプラグインを作ってみたDevice WebAPI Consortium
 
参加したセッションの ピックアップ
参加したセッションのピックアップ参加したセッションのピックアップ
参加したセッションの ピックアップ健一 辰濱
 
GitHubを導入したいとき、どう説得していこう #GitHubSatelliteTokyo
GitHubを導入したいとき、どう説得していこう #GitHubSatelliteTokyoGitHubを導入したいとき、どう説得していこう #GitHubSatelliteTokyo
GitHubを導入したいとき、どう説得していこう #GitHubSatelliteTokyoYahoo!デベロッパーネットワーク
 
データで散らかった製造業界における最高の翻訳機 Node-RED
データで散らかった製造業界における最高の翻訳機 Node-REDデータで散らかった製造業界における最高の翻訳機 Node-RED
データで散らかった製造業界における最高の翻訳機 Node-REDnodered_ug_jp
 
音声によるデバイスWebAPIの操作
音声によるデバイスWebAPIの操作音声によるデバイスWebAPIの操作
音声によるデバイスWebAPIの操作Device WebAPI Consortium
 

What's hot (20)

SQLiteDatabaseを無理矢理覗く
SQLiteDatabaseを無理矢理覗くSQLiteDatabaseを無理矢理覗く
SQLiteDatabaseを無理矢理覗く
 
私たち企業がアクセシビリティに取り組む理由(2018年) #accfes
私たち企業がアクセシビリティに取り組む理由(2018年) #accfes私たち企業がアクセシビリティに取り組む理由(2018年) #accfes
私たち企業がアクセシビリティに取り組む理由(2018年) #accfes
 
Hint of“Passcode Lock”Screen and Logic (with LocalAuthentication).
Hint of“Passcode Lock”Screen and Logic (with LocalAuthentication).Hint of“Passcode Lock”Screen and Logic (with LocalAuthentication).
Hint of“Passcode Lock”Screen and Logic (with LocalAuthentication).
 
AndroidのAR最新動向
AndroidのAR最新動向AndroidのAR最新動向
AndroidのAR最新動向
 
[GrapeCity Web TECH FORUM 2018]グレープシティJavaScript製品のご紹介 活用のコツと開発のポイント
[GrapeCity Web TECH FORUM 2018]グレープシティJavaScript製品のご紹介 活用のコツと開発のポイント[GrapeCity Web TECH FORUM 2018]グレープシティJavaScript製品のご紹介 活用のコツと開発のポイント
[GrapeCity Web TECH FORUM 2018]グレープシティJavaScript製品のご紹介 活用のコツと開発のポイント
 
Intro to OMA GotAPI Open-Source Implementation Supporting Web - Healthcare Us...
Intro to OMA GotAPI Open-Source Implementation Supporting Web - Healthcare Us...Intro to OMA GotAPI Open-Source Implementation Supporting Web - Healthcare Us...
Intro to OMA GotAPI Open-Source Implementation Supporting Web - Healthcare Us...
 
MozOpenHardプロジェクトと そのコア技術について
MozOpenHardプロジェクトと そのコア技術についてMozOpenHardプロジェクトと そのコア技術について
MozOpenHardプロジェクトと そのコア技術について
 
DevRel Meetup27 Igarashi-pub
DevRel Meetup27 Igarashi-pubDevRel Meetup27 Igarashi-pub
DevRel Meetup27 Igarashi-pub
 
インテル Real Sense Hands On Lab
インテル Real Sense Hands On Labインテル Real Sense Hands On Lab
インテル Real Sense Hands On Lab
 
Presentation 2
Presentation 2Presentation 2
Presentation 2
 
OMA GotAPI 標準化作業状況アップデート
OMA GotAPI 標準化作業状況アップデートOMA GotAPI 標準化作業状況アップデート
OMA GotAPI 標準化作業状況アップデート
 
DeviceConnect向けCordovaプラグインを作ってみた
DeviceConnect向けCordovaプラグインを作ってみたDeviceConnect向けCordovaプラグインを作ってみた
DeviceConnect向けCordovaプラグインを作ってみた
 
DevOps with GitLabで始める簡単DevOps
DevOps with GitLabで始める簡単DevOpsDevOps with GitLabで始める簡単DevOps
DevOps with GitLabで始める簡単DevOps
 
参加したセッションの ピックアップ
参加したセッションのピックアップ参加したセッションのピックアップ
参加したセッションの ピックアップ
 
GitHubを導入したいとき、どう説得していこう #GitHubSatelliteTokyo
GitHubを導入したいとき、どう説得していこう #GitHubSatelliteTokyoGitHubを導入したいとき、どう説得していこう #GitHubSatelliteTokyo
GitHubを導入したいとき、どう説得していこう #GitHubSatelliteTokyo
 
データで散らかった製造業界における最高の翻訳機 Node-RED
データで散らかった製造業界における最高の翻訳機 Node-REDデータで散らかった製造業界における最高の翻訳機 Node-RED
データで散らかった製造業界における最高の翻訳機 Node-RED
 
WinActor20191113
WinActor20191113WinActor20191113
WinActor20191113
 
Yahoo! JAPAN MEETUP #21~Gitを使ったチーム開発体験@名古屋~
Yahoo! JAPAN MEETUP #21~Gitを使ったチーム開発体験@名古屋~ Yahoo! JAPAN MEETUP #21~Gitを使ったチーム開発体験@名古屋~
Yahoo! JAPAN MEETUP #21~Gitを使ったチーム開発体験@名古屋~
 
音声によるデバイスWebAPIの操作
音声によるデバイスWebAPIの操作音声によるデバイスWebAPIの操作
音声によるデバイスWebAPIの操作
 
アプリのプロダクトマネージャーからみるScrum開発
アプリのプロダクトマネージャーからみるScrum開発アプリのプロダクトマネージャーからみるScrum開発
アプリのプロダクトマネージャーからみるScrum開発
 

Similar to Spring I/O 2018 報告 RESTDocs RAML, Cloud Contract

Angular でもっとAPIファースト・もっとモダンデザインなWebアプリケーションを作ろう!
Angular でもっとAPIファースト・もっとモダンデザインなWebアプリケーションを作ろう!Angular でもっとAPIファースト・もっとモダンデザインなWebアプリケーションを作ろう!
Angular でもっとAPIファースト・もっとモダンデザインなWebアプリケーションを作ろう!CData Software Japan
 
デバイスWebAPI/Symphonyを軸としたIoTの展開について
デバイスWebAPI/Symphonyを軸としたIoTの展開についてデバイスWebAPI/Symphonyを軸としたIoTの展開について
デバイスWebAPI/Symphonyを軸としたIoTの展開についてDevice WebAPI Consortium
 
Jazug-8th: Azure AKS & FIWARE & Robot
Jazug-8th: Azure AKS & FIWARE & RobotJazug-8th: Azure AKS & FIWARE & Robot
Jazug-8th: Azure AKS & FIWARE & RobotNobuyuki Matsui
 
Introduction to NetOpsCoding
Introduction to NetOpsCodingIntroduction to NetOpsCoding
Introduction to NetOpsCodingTaiji Tsuchiya
 
OpenStack Swiftとそのエコシステムの最新動向
OpenStack Swiftとそのエコシステムの最新動向OpenStack Swiftとそのエコシステムの最新動向
OpenStack Swiftとそのエコシステムの最新動向NTT Software Innovation Center
 
WebRTCを始めよう! HTML5fun 第一回勉強会
WebRTCを始めよう! HTML5fun 第一回勉強会WebRTCを始めよう! HTML5fun 第一回勉強会
WebRTCを始めよう! HTML5fun 第一回勉強会Yusuke Naka
 
【Logic Apps編】ノンコーディングでデキる!お問い合わせフォーム機能拡張
【Logic Apps編】ノンコーディングでデキる!お問い合わせフォーム機能拡張【Logic Apps編】ノンコーディングでデキる!お問い合わせフォーム機能拡張
【Logic Apps編】ノンコーディングでデキる!お問い合わせフォーム機能拡張典子 松本
 
チラシルiOSでの広告枠開発
チラシルiOSでの広告枠開発チラシルiOSでの広告枠開発
チラシルiOSでの広告枠開発Satoshi Takano
 
SkyWay国内唯一のCPaaS
SkyWay国内唯一のCPaaSSkyWay国内唯一のCPaaS
SkyWay国内唯一のCPaaSKensaku Komatsu
 
Spring I/O 2019 報告 Spring Frameworkのロードマップと5.2の新機能
Spring I/O 2019 報告 Spring Frameworkのロードマップと5.2の新機能Spring I/O 2019 報告 Spring Frameworkのロードマップと5.2の新機能
Spring I/O 2019 報告 Spring Frameworkのロードマップと5.2の新機能Takuya Iwatsuka
 
第六回コンテナ型仮想化情報交換会_LinuxContainerLivemigrationCRIU
第六回コンテナ型仮想化情報交換会_LinuxContainerLivemigrationCRIU第六回コンテナ型仮想化情報交換会_LinuxContainerLivemigrationCRIU
第六回コンテナ型仮想化情報交換会_LinuxContainerLivemigrationCRIUKengo Okitsu
 
情報処理学会第77回全国大会 3月17日 於 京都大学 1G-07 国際標準における 参照ソフトウエアと特許の扱い
情報処理学会第77回全国大会 3月17日 於 京都大学 1G-07 国際標準における参照ソフトウエアと特許の扱い情報処理学会第77回全国大会 3月17日 於 京都大学 1G-07 国際標準における参照ソフトウエアと特許の扱い
情報処理学会第77回全国大会 3月17日 於 京都大学 1G-07 国際標準における 参照ソフトウエアと特許の扱いItaru Kaneko
 
技術選択とアーキテクトの役割
技術選択とアーキテクトの役割技術選択とアーキテクトの役割
技術選択とアーキテクトの役割Toru Yamaguchi
 

Similar to Spring I/O 2018 報告 RESTDocs RAML, Cloud Contract (20)

Angular でもっとAPIファースト・もっとモダンデザインなWebアプリケーションを作ろう!
Angular でもっとAPIファースト・もっとモダンデザインなWebアプリケーションを作ろう!Angular でもっとAPIファースト・もっとモダンデザインなWebアプリケーションを作ろう!
Angular でもっとAPIファースト・もっとモダンデザインなWebアプリケーションを作ろう!
 
OSS光と闇
OSS光と闇OSS光と闇
OSS光と闇
 
Spring I/O 2015 報告
Spring I/O 2015 報告Spring I/O 2015 報告
Spring I/O 2015 報告
 
Spring social の基礎
Spring social の基礎Spring social の基礎
Spring social の基礎
 
デバイスWebAPI/Symphonyを軸としたIoTの展開について
デバイスWebAPI/Symphonyを軸としたIoTの展開についてデバイスWebAPI/Symphonyを軸としたIoTの展開について
デバイスWebAPI/Symphonyを軸としたIoTの展開について
 
Jazug-8th: Azure AKS & FIWARE & Robot
Jazug-8th: Azure AKS & FIWARE & RobotJazug-8th: Azure AKS & FIWARE & Robot
Jazug-8th: Azure AKS & FIWARE & Robot
 
Introduction to NetOpsCoding
Introduction to NetOpsCodingIntroduction to NetOpsCoding
Introduction to NetOpsCoding
 
OpenStack Swiftとそのエコシステムの最新動向
OpenStack Swiftとそのエコシステムの最新動向OpenStack Swiftとそのエコシステムの最新動向
OpenStack Swiftとそのエコシステムの最新動向
 
WebRTCを始めよう! HTML5fun 第一回勉強会
WebRTCを始めよう! HTML5fun 第一回勉強会WebRTCを始めよう! HTML5fun 第一回勉強会
WebRTCを始めよう! HTML5fun 第一回勉強会
 
【Logic Apps編】ノンコーディングでデキる!お問い合わせフォーム機能拡張
【Logic Apps編】ノンコーディングでデキる!お問い合わせフォーム機能拡張【Logic Apps編】ノンコーディングでデキる!お問い合わせフォーム機能拡張
【Logic Apps編】ノンコーディングでデキる!お問い合わせフォーム機能拡張
 
Spring tools4
Spring tools4Spring tools4
Spring tools4
 
【初心者向け】API を使ってクラウドの管理を自動化しよう
【初心者向け】API を使ってクラウドの管理を自動化しよう【初心者向け】API を使ってクラウドの管理を自動化しよう
【初心者向け】API を使ってクラウドの管理を自動化しよう
 
チラシルiOSでの広告枠開発
チラシルiOSでの広告枠開発チラシルiOSでの広告枠開発
チラシルiOSでの広告枠開発
 
SkyWay国内唯一のCPaaS
SkyWay国内唯一のCPaaSSkyWay国内唯一のCPaaS
SkyWay国内唯一のCPaaS
 
Spring I/O 2019 報告 Spring Frameworkのロードマップと5.2の新機能
Spring I/O 2019 報告 Spring Frameworkのロードマップと5.2の新機能Spring I/O 2019 報告 Spring Frameworkのロードマップと5.2の新機能
Spring I/O 2019 報告 Spring Frameworkのロードマップと5.2の新機能
 
第六回コンテナ型仮想化情報交換会_LinuxContainerLivemigrationCRIU
第六回コンテナ型仮想化情報交換会_LinuxContainerLivemigrationCRIU第六回コンテナ型仮想化情報交換会_LinuxContainerLivemigrationCRIU
第六回コンテナ型仮想化情報交換会_LinuxContainerLivemigrationCRIU
 
YJTC18 A-1 大規模サーバの戦略
YJTC18 A-1 大規模サーバの戦略YJTC18 A-1 大規模サーバの戦略
YJTC18 A-1 大規模サーバの戦略
 
情報処理学会第77回全国大会 3月17日 於 京都大学 1G-07 国際標準における 参照ソフトウエアと特許の扱い
情報処理学会第77回全国大会 3月17日 於 京都大学 1G-07 国際標準における参照ソフトウエアと特許の扱い情報処理学会第77回全国大会 3月17日 於 京都大学 1G-07 国際標準における参照ソフトウエアと特許の扱い
情報処理学会第77回全国大会 3月17日 於 京都大学 1G-07 国際標準における 参照ソフトウエアと特許の扱い
 
SkyWay HandsOn
SkyWay HandsOnSkyWay HandsOn
SkyWay HandsOn
 
技術選択とアーキテクトの役割
技術選択とアーキテクトの役割技術選択とアーキテクトの役割
技術選択とアーキテクトの役割
 

More from Takuya Iwatsuka

SpringとGrarlVM Native Image -2019/12-
SpringとGrarlVM Native Image -2019/12-SpringとGrarlVM Native Image -2019/12-
SpringとGrarlVM Native Image -2019/12-Takuya Iwatsuka
 
SpringOne Platform 2018 全体報告
SpringOne Platform 2018 全体報告SpringOne Platform 2018 全体報告
SpringOne Platform 2018 全体報告Takuya Iwatsuka
 
SpringOne Platform 2017報告会 メインプロジェクトのアップデート
SpringOne Platform 2017報告会 メインプロジェクトのアップデートSpringOne Platform 2017報告会 メインプロジェクトのアップデート
SpringOne Platform 2017報告会 メインプロジェクトのアップデートTakuya Iwatsuka
 
Spring Security 5.0 解剖速報
Spring Security 5.0 解剖速報Spring Security 5.0 解剖速報
Spring Security 5.0 解剖速報Takuya Iwatsuka
 
Spring I/O 2017 報告 ThymeleafのWebFlux対応
Spring I/O 2017 報告 ThymeleafのWebFlux対応Spring I/O 2017 報告 ThymeleafのWebFlux対応
Spring I/O 2017 報告 ThymeleafのWebFlux対応Takuya Iwatsuka
 
Spring 5に備えるリアクティブプログラミング入門
Spring 5に備えるリアクティブプログラミング入門Spring 5に備えるリアクティブプログラミング入門
Spring 5に備えるリアクティブプログラミング入門Takuya Iwatsuka
 
SpringOne 2016 報告 Reactive APIの設計・実装・使用
SpringOne 2016 報告 Reactive APIの設計・実装・使用SpringOne 2016 報告 Reactive APIの設計・実装・使用
SpringOne 2016 報告 Reactive APIの設計・実装・使用Takuya Iwatsuka
 
Spring I/O 2016 報告 Test / Cloud / Other Popular Sessions
Spring I/O 2016 報告 Test / Cloud / Other Popular SessionsSpring I/O 2016 報告 Test / Cloud / Other Popular Sessions
Spring I/O 2016 報告 Test / Cloud / Other Popular SessionsTakuya Iwatsuka
 
Password validation with Passay
Password validation with PassayPassword validation with Passay
Password validation with PassayTakuya Iwatsuka
 

More from Takuya Iwatsuka (9)

SpringとGrarlVM Native Image -2019/12-
SpringとGrarlVM Native Image -2019/12-SpringとGrarlVM Native Image -2019/12-
SpringとGrarlVM Native Image -2019/12-
 
SpringOne Platform 2018 全体報告
SpringOne Platform 2018 全体報告SpringOne Platform 2018 全体報告
SpringOne Platform 2018 全体報告
 
SpringOne Platform 2017報告会 メインプロジェクトのアップデート
SpringOne Platform 2017報告会 メインプロジェクトのアップデートSpringOne Platform 2017報告会 メインプロジェクトのアップデート
SpringOne Platform 2017報告会 メインプロジェクトのアップデート
 
Spring Security 5.0 解剖速報
Spring Security 5.0 解剖速報Spring Security 5.0 解剖速報
Spring Security 5.0 解剖速報
 
Spring I/O 2017 報告 ThymeleafのWebFlux対応
Spring I/O 2017 報告 ThymeleafのWebFlux対応Spring I/O 2017 報告 ThymeleafのWebFlux対応
Spring I/O 2017 報告 ThymeleafのWebFlux対応
 
Spring 5に備えるリアクティブプログラミング入門
Spring 5に備えるリアクティブプログラミング入門Spring 5に備えるリアクティブプログラミング入門
Spring 5に備えるリアクティブプログラミング入門
 
SpringOne 2016 報告 Reactive APIの設計・実装・使用
SpringOne 2016 報告 Reactive APIの設計・実装・使用SpringOne 2016 報告 Reactive APIの設計・実装・使用
SpringOne 2016 報告 Reactive APIの設計・実装・使用
 
Spring I/O 2016 報告 Test / Cloud / Other Popular Sessions
Spring I/O 2016 報告 Test / Cloud / Other Popular SessionsSpring I/O 2016 報告 Test / Cloud / Other Popular Sessions
Spring I/O 2016 報告 Test / Cloud / Other Popular Sessions
 
Password validation with Passay
Password validation with PassayPassword validation with Passay
Password validation with Passay
 

Recently uploaded

PHP-Conference-Odawara-2024-04-000000000
PHP-Conference-Odawara-2024-04-000000000PHP-Conference-Odawara-2024-04-000000000
PHP-Conference-Odawara-2024-04-000000000Shota Ito
 
IoT in the era of generative AI, Thanks IoT ALGYAN.pptx
IoT in the era of generative AI, Thanks IoT ALGYAN.pptxIoT in the era of generative AI, Thanks IoT ALGYAN.pptx
IoT in the era of generative AI, Thanks IoT ALGYAN.pptxAtomu Hidaka
 
新人研修のまとめ 2024/04/12の勉強会で発表されたものです。
新人研修のまとめ       2024/04/12の勉強会で発表されたものです。新人研修のまとめ       2024/04/12の勉強会で発表されたものです。
新人研修のまとめ 2024/04/12の勉強会で発表されたものです。iPride Co., Ltd.
 
プレイマットのパターン生成支援ツールの評価
プレイマットのパターン生成支援ツールの評価プレイマットのパターン生成支援ツールの評価
プレイマットのパターン生成支援ツールの評価sugiuralab
 
20240412_HCCJP での Windows Server 2025 Active Directory
20240412_HCCJP での Windows Server 2025 Active Directory20240412_HCCJP での Windows Server 2025 Active Directory
20240412_HCCJP での Windows Server 2025 Active Directoryosamut
 
プレイマットのパターン生成支援ツール
プレイマットのパターン生成支援ツールプレイマットのパターン生成支援ツール
プレイマットのパターン生成支援ツールsugiuralab
 
Amazon SES を勉強してみる その12024/04/12の勉強会で発表されたものです。
Amazon SES を勉強してみる その12024/04/12の勉強会で発表されたものです。Amazon SES を勉強してみる その12024/04/12の勉強会で発表されたものです。
Amazon SES を勉強してみる その12024/04/12の勉強会で発表されたものです。iPride Co., Ltd.
 

Recently uploaded (7)

PHP-Conference-Odawara-2024-04-000000000
PHP-Conference-Odawara-2024-04-000000000PHP-Conference-Odawara-2024-04-000000000
PHP-Conference-Odawara-2024-04-000000000
 
IoT in the era of generative AI, Thanks IoT ALGYAN.pptx
IoT in the era of generative AI, Thanks IoT ALGYAN.pptxIoT in the era of generative AI, Thanks IoT ALGYAN.pptx
IoT in the era of generative AI, Thanks IoT ALGYAN.pptx
 
新人研修のまとめ 2024/04/12の勉強会で発表されたものです。
新人研修のまとめ       2024/04/12の勉強会で発表されたものです。新人研修のまとめ       2024/04/12の勉強会で発表されたものです。
新人研修のまとめ 2024/04/12の勉強会で発表されたものです。
 
プレイマットのパターン生成支援ツールの評価
プレイマットのパターン生成支援ツールの評価プレイマットのパターン生成支援ツールの評価
プレイマットのパターン生成支援ツールの評価
 
20240412_HCCJP での Windows Server 2025 Active Directory
20240412_HCCJP での Windows Server 2025 Active Directory20240412_HCCJP での Windows Server 2025 Active Directory
20240412_HCCJP での Windows Server 2025 Active Directory
 
プレイマットのパターン生成支援ツール
プレイマットのパターン生成支援ツールプレイマットのパターン生成支援ツール
プレイマットのパターン生成支援ツール
 
Amazon SES を勉強してみる その12024/04/12の勉強会で発表されたものです。
Amazon SES を勉強してみる その12024/04/12の勉強会で発表されたものです。Amazon SES を勉強してみる その12024/04/12の勉強会で発表されたものです。
Amazon SES を勉強してみる その12024/04/12の勉強会で発表されたものです。
 

Spring I/O 2018 報告 RESTDocs RAML, Cloud Contract

  • 1. Copyright©2018 NTT corp. All Rights Reserved. Spring I/O 2018 報告会 2018年7月30日 NTTソフトウェアイノベーションセンタ 岩塚 卓弥
  • 2. 2Copyright©2018 NTT corp. All Rights Reserved. • 名前:岩塚 卓弥 • 所属:NTT ソフトウェアイノベーションセンタ • NTTの研究所のうちソフトウェアを専門に扱う • 自部署ではソフトウェア工学を研究 • Springベースのグループ共通フレームワークの整備を担当 • Spring I/O は今年で4回目 • レポートも書きました(共著) • https://codezine.jp/article/detail/10930 自己紹介
  • 3. 3Copyright©2018 NTT corp. All Rights Reserved. • Documenting RESTful APIs with Spring REST Docs and RAML • スライド: https://speakerdeck.com/mduesterhoeft/documenting- restful-apis-with-spring-rest-docs-and-raml • 動画: https://www.youtube.com/watch?v=VwKc34W96Cw&li st=PLe6FX2SlkJdRCNFdhWgpRmJybXafo-Uqk&index=20 • Consumer driven contracts in a polyglot world • スライド: https://docs.google.com/presentation/d/19BFGJiTElU3 VVIbpF3Gqac26m4uaNpPEQpVB1eIPa90/edit#slide=id. p • 動画: https://www.youtube.com/watch?v=sKlwNJeQMV4&list =PLe6FX2SlkJdRCNFdhWgpRmJybXafo-Uqk&index=25 今日のトピック
  • 4. 4Copyright©2018 NTT corp. All Rights Reserved. REST Docs (and RAML)のセッションのQ&Aで Spring Cloud Contract との関連を問う質問があった → セッションの内容とはコンテキストが違い,要領を得ず キーワードレベル(API, テスト)で共通しているため, うまく整理できていない人が多いのかも… きっかけ
  • 5. 5Copyright©2018 NTT corp. All Rights Reserved. RESTful API 開発
  • 6. 6Copyright©2018 NTT corp. All Rights Reserved. 用途による分類 Public API Internal API App API 3rd party App 3rd party App 3rd party App • 誰がどう使うかわからない • API変更時に利用側の合意は不要 • そもそも全員の合意は取れない • 外部の開発者に使ってもらうための 諸々を用意する必要がある • 使う人・使用方法がわかっている • API変更時に利用側の合意が必要 • 勝手に変えると他のサービスが 壊れる場合がある • 内部の開発者が使えればよい App API App App AppAPI API API
  • 7. 7Copyright©2018 NTT corp. All Rights Reserved. 使えない / 使いたくない API • そもそも欲しい機能がAPI化されていない • ドキュメントがない • ドキュメントが古い • ドキュメントがわかりにくい 合体技 わかりにくいドキュメントをくまなく調べた結果 欲しい機能がAPIとして提供されていないことがわかる 使ってもらうためにドキュメントは必須 特に Public API の場合は充実したドキュメントがあるとよい APIドキュメントの必要性
  • 8. 8Copyright©2018 NTT corp. All Rights Reserved. 多くの開発者の共通認識 • メンテナンスされたドキュメントは重要である • ドキュメントのメンテナンスは面倒である ドキュメントのメンテナンス なんらかの方法でドキュメントが勝手に実装に追従してくれると嬉しい → いくつかのアプローチがあるが,いずれにせよ何らかの妥協が必要
  • 9. 9Copyright©2018 NTT corp. All Rights Reserved. 機械可読の仕様から実装もドキュメントも生成 API仕様からの生成 Spec 本当に仕様から吐き出されるソースコードと付き合っていけるか? → できないと結局ドキュメントのメンテナンス面倒問題と同じ構図に 記法は様々 ・OpenAPI ・RAML ・API Blueprint ・... ツールによって用途も様々 ドキュメント ソースコード スタブ(モック)サーバ ...
  • 10. 10Copyright©2018 NTT corp. All Rights Reserved. 実装そのものからドキュメントを生成 一般に,ソースコードだけでは情報が足りないので補完が必要 ソースコードからの生成 e.g. Springfox • 実装方法に依存する • ソースコードが読みづらくなる • 実装内容と補完情報が乖離していないことは保証されない
  • 11. 11Copyright©2018 NTT corp. All Rights Reserved. APIのテストコードからドキュメントの一部を生成 • API実装側の実装方法に依存しない • テストされた確実な内容を出力 • デフォルトでは Asciidoctor のスニペットとして出力 • テストが失敗した場合は出力しない Spring REST Docs ...
  • 12. 12Copyright©2018 NTT corp. All Rights Reserved. Spring REST Docs ドキュメント例 生成したスニペットをincludeしてドキュメントを作成
  • 13. 13Copyright©2018 NTT corp. All Rights Reserved. Spring REST Docs • テストを利用した正確な出力 😊 • Asciidoctor (or Markdown) のスニペットを出力 😐 • ドキュメントが静的かつ簡素 • 用途が限定的 Spring REST Docs RAML Integration • RAML形式の出力をサポートしたサードパーティ拡張 • https://github.com/ePages-de/restdocs-raml • 実装との乖離を防ぎつつ RAML のエコシステムを活用 Spring REST Docs の拡張
  • 14. 14Copyright©2018 NTT corp. All Rights Reserved. restdoc-raml の入力例 Spring REST Docs を拡張
  • 15. 15Copyright©2018 NTT corp. All Rights Reserved. restdoc-raml の出力例 RAML JsonSchema リクエスト例
  • 16. 16Copyright©2018 NTT corp. All Rights Reserved. RAMLの活用(raml2html)
  • 17. 17Copyright©2018 NTT corp. All Rights Reserved. RAMLの活用(raml2html)
  • 18. 18Copyright©2018 NTT corp. All Rights Reserved. RAMLの活用 (API console)
  • 19. 19Copyright©2018 NTT corp. All Rights Reserved. RAMLの活用 (API console)
  • 20. 20Copyright©2018 NTT corp. All Rights Reserved. Documenting RESTful APIs with Spring REST Docs and RAML • Public API を使ってもらうためにドキュメントが必要 • テストから生成する Spring REST Docs のアプローチを採用 • Asciidoctor の静的なドキュメントでは物足りない → テストから RAML を生成する拡張を作った RAMLのエコシステムを活用できるようになった - 動的なドキュメント - ブラウザで動作するクライアント - スタブ(モック)サーバの作成 - … ここまでのまとめ
  • 21. 21Copyright©2018 NTT corp. All Rights Reserved. 【再掲】用途による分類 Public API Internal API App API 3rd party App 3rd party App 3rd party App • 誰がどう使うかわからない • API変更時に利用側の合意は不要 • そもそも全員の合意は取れない • 外部の開発者に使ってもらうための 諸々を用意する必要がある • 使う人も使われ方もわかっている • API変更時に利用側の合意が必要 • 勝手に変えると他のサービスが 壊れる場合がある • 内部の開発者が使えればよい App API App App AppAPI API API
  • 22. 22Copyright©2018 NTT corp. All Rights Reserved. Consumer-driven Contracts (CdC) App API App App App 提供者 (Provider) 利用者 (Consumer)Contract Contract • API提供者と利用者のリクエスト/レスポンスに関する取り決め • 各利用者はAPIのレスポンスのすべてを使いたいとは限らない • 利用者の必要な部分だけの取り決め = Consumer Contract • 提供者は各利用者との Contract に合意し,これを守る Contract を前提とすることで対向をスタブ化したテストが可能になる
  • 23. 23Copyright©2018 NTT corp. All Rights Reserved. Spring Cloud Contract – Contractの記述 App API App 提供者 (Provider) 利用者 (Consumer) Contract Groovy DSL または YAML で記述
  • 24. 24Copyright©2018 NTT corp. All Rights Reserved. Spring Cloud Contract – Providerのテスト App API App 提供者 (Provider) 利用者 (Consumer) Contract テストテストテスト テストコードの生成 リクエストに対して Contractの通りレスポンスするか
  • 25. 25Copyright©2018 NTT corp. All Rights Reserved. Spring Cloud Contract – テスト用スタブ App API App 提供者 (Provider) 利用者 (Consumer) Contract スタブ スタブを生成 実体は jar ファイル Contract に対応した WireMock用のjsonが 入っている
  • 26. 26Copyright©2018 NTT corp. All Rights Reserved. Spring Cloud Contract – Consumerのテスト App API App 提供者 (Provider) 利用者 (Consumer) Contract スタブ スタブを利用してテスト 使用するスタブを指定
  • 27. 27Copyright©2018 NTT corp. All Rights Reserved. Microservices ではJVM言語以外も自然に混在しえる → Java, maven に依存しないやり方が必要 Spring Cloud Contract の Polyglot 対応 • Contract の記述 → Groovy DSL 以外に YAML でも記述可能 • Provider のテストコードの生成 → Docker でテスト生成&実行 • Consumer テスト用のスタブ生成 → Docker でスタブ生成&実行 Polyglot 対応
  • 28. 28Copyright©2018 NTT corp. All Rights Reserved. Polyglot 対応 – Contractの記述 App API App 提供者 (Provider) 利用者 (Consumer) Contract YAML で記述
  • 29. 29Copyright©2018 NTT corp. All Rights Reserved. Polyglot 対応 – Providerのテスト App API App 提供者 (Provider) 利用者 (Consumer) Contract テストテストテスト 生成 起動しておく マウント spring-cloud-contract Providerにリクエストして レスポンスを検証
  • 30. 30Copyright©2018 NTT corp. All Rights Reserved. Polyglot 対応 – テスト用スタブ App API App 提供者 (Provider) 利用者 (Consumer) Contract スタブ 生成 Artifactoryへpublishされる
  • 31. 31Copyright©2018 NTT corp. All Rights Reserved. Polyglot 対応 – Consumerのテスト App API App 提供者 (Provider) 利用者 (Consumer) Contract スタブ spring-cloud-contract-stub-runner Artifactoryから 取得して起動 テストのリクエストに レスポンスを返す
  • 32. 32Copyright©2018 NTT corp. All Rights Reserved. REST Docs を利用すると以下が可能 • テストコードからのスタブ生成 • テストコードからのContract生成 → 既にSpring MVCのテストがあるプロジェクトで, Spring Cloud Contract を新しく導入するときに便利 Spring Cloud Contract + REST Docs
  • 33. 33Copyright©2018 NTT corp. All Rights Reserved. • Documenting RESTful APIs with Spring REST Docs and RAML • 実装と対応したドキュメントを作成するにはテストをソースに するとよい • Spring RESTDocs のコンセプトはそのままにRAMLのエコシ ステムを利用できる拡張を作った • Consumer driven contracts in a polyglot world • 内部APIの連携の試験にはCdCが便利 • Spring Cloud Contract は非JVM環境にも対応 • 目的に沿った技術を使う • キーワードだけで捉えると見誤る • ツールに振り回されないようにコンテキストを整理すること まとめ