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

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
自己紹介

• 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
今日のトピック

REST Docs (and RAML)のセッションのQ&Aで
Spring Cloud Contract との関連を問う質問があった
→ セッションの内容とはコンテキストが違い，要領を得ず
キーワードレベル(API, テスト)で共通しているため，
うまく整理できていない人が多いのかも…
きっかけ

RESTful API 開発

用途による分類
Public API Internal API
App
API
3rd party App 3rd party App
3rd party App
• 誰がどう使うかわからない
• API変更時に利用側の合意は不要
• そもそも全員の合意は取れない
• 外部の開発者に使ってもらうための
諸々を用意する必要がある
• 使う人・使用方法がわかっている
• API変更時に利用側の合意が必要
• 勝手に変えると他のサービスが
壊れる場合がある
• 内部の開発者が使えればよい
App
API
App
App
AppAPI API
API

使えない / 使いたくない API
• そもそも欲しい機能がAPI化されていない
• ドキュメントがない
• ドキュメントが古い
• ドキュメントがわかりにくい
合体技
わかりにくいドキュメントをくまなく調べた結果
欲しい機能がAPIとして提供されていないことがわかる
使ってもらうためにドキュメントは必須
特に Public API の場合は充実したドキュメントがあるとよい
APIドキュメントの必要性

多くの開発者の共通認識
• メンテナンスされたドキュメントは重要である
• ドキュメントのメンテナンスは面倒である
ドキュメントのメンテナンス
なんらかの方法でドキュメントが勝手に実装に追従してくれると嬉しい
→ いくつかのアプローチがあるが，いずれにせよ何らかの妥協が必要

機械可読の仕様から実装もドキュメントも生成
API仕様からの生成
Spec
本当に仕様から吐き出されるソースコードと付き合っていけるか？
→ できないと結局ドキュメントのメンテナンス面倒問題と同じ構図に
記法は様々
・OpenAPI
・RAML
・API Blueprint
・...
ツールによって用途も様々
ドキュメント
ソースコード
スタブ（モック）サーバ
...

実装そのものからドキュメントを生成
一般に，ソースコードだけでは情報が足りないので補完が必要
ソースコードからの生成
e.g. Springfox
• 実装方法に依存する
• ソースコードが読みづらくなる
• 実装内容と補完情報が乖離していないことは保証されない

APIのテストコードからドキュメントの一部を生成
• API実装側の実装方法に依存しない
• テストされた確実な内容を出力
• デフォルトでは Asciidoctor のスニペットとして出力
• テストが失敗した場合は出力しない
Spring REST Docs
...

Spring REST Docs ドキュメント例
生成したスニペットをincludeしてドキュメントを作成

Spring REST Docs
• テストを利用した正確な出力 😊
• Asciidoctor (or Markdown) のスニペットを出力 😐
• ドキュメントが静的かつ簡素
• 用途が限定的
Spring REST Docs RAML Integration
• RAML形式の出力をサポートしたサードパーティ拡張
• https://github.com/ePages-de/restdocs-raml
• 実装との乖離を防ぎつつ RAML のエコシステムを活用
Spring REST Docs の拡張

restdoc-raml の入力例
Spring REST Docs を拡張

restdoc-raml の出力例
RAML
JsonSchema
リクエスト例

RAMLの活用（raml2html）

RAMLの活用 (API console)

Documenting RESTful APIs with Spring REST Docs
and RAML
• Public API を使ってもらうためにドキュメントが必要
• テストから生成する Spring REST Docs のアプローチを採用
• Asciidoctor の静的なドキュメントでは物足りない
→ テストから RAML を生成する拡張を作った
RAMLのエコシステムを活用できるようになった
- 動的なドキュメント
- ブラウザで動作するクライアント
- スタブ（モック）サーバの作成
- …
ここまでのまとめ

【再掲】用途による分類
Public API Internal API
App
API
3rd party App 3rd party App
3rd party App
• 誰がどう使うかわからない
• API変更時に利用側の合意は不要
• そもそも全員の合意は取れない
• 外部の開発者に使ってもらうための
諸々を用意する必要がある
• 使う人も使われ方もわかっている
• API変更時に利用側の合意が必要
• 勝手に変えると他のサービスが
壊れる場合がある
• 内部の開発者が使えればよい
App
API
App
App
AppAPI API
API

Consumer-driven Contracts (CdC)
App API
App
App
App
提供者 (Provider)
利用者 (Consumer)Contract
Contract
• API提供者と利用者のリクエスト/レスポンスに関する取り決め
• 各利用者はAPIのレスポンスのすべてを使いたいとは限らない
• 利用者の必要な部分だけの取り決め = Consumer Contract
• 提供者は各利用者との Contract に合意し，これを守る
Contract を前提とすることで対向をスタブ化したテストが可能になる

Spring Cloud Contract – Contractの記述
App API App
提供者 (Provider) 利用者 (Consumer)
Contract
Groovy DSL または YAML で記述

Spring Cloud Contract – Providerのテスト
App API App
Contract
テストテストテストテストコードの生成
リクエストに対して
Contractの通りレスポンスするか

Spring Cloud Contract – テスト用スタブ
App API App
Contract
スタブ
スタブを生成
実体は jar ファイル
Contract に対応した
WireMock用のjsonが
入っている

Spring Cloud Contract – Consumerのテスト
App API App
Contract
スタブ
スタブを利用してテスト
使用するスタブを指定

Microservices ではJVM言語以外も自然に混在しえる
→ Java, maven に依存しないやり方が必要
Spring Cloud Contract の Polyglot 対応
• Contract の記述
→ Groovy DSL 以外に YAML でも記述可能
• Provider のテストコードの生成
→ Docker でテスト生成＆実行
• Consumer テスト用のスタブ生成
→ Docker でスタブ生成&実行
Polyglot 対応

Polyglot 対応 – Contractの記述
App API App
Contract
YAML で記述

Polyglot 対応 – Providerのテスト
App API App
Contract
テストテストテスト
生成
起動しておくマウント
spring-cloud-contract
Providerにリクエストして
レスポンスを検証

Polyglot 対応 – テスト用スタブ
App API App
Contract
スタブ
生成
Artifactoryへpublishされる

Polyglot 対応 – Consumerのテスト
App API App
Contract
スタブ
spring-cloud-contract-stub-runner
Artifactoryから
取得して起動
テストのリクエストに
レスポンスを返す

REST Docs を利用すると以下が可能
• テストコードからのスタブ生成
• テストコードからのContract生成
→ 既にSpring MVCのテストがあるプロジェクトで，
Spring Cloud Contract を新しく導入するときに便利
Spring Cloud Contract + REST Docs

• 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環境にも対応
• 目的に沿った技術を使う
• キーワードだけで捉えると見誤る
• ツールに振り回されないようにコンテキストを整理すること
まとめ

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

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

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

Semelhante a Spring I/O 2018 報告 RESTDocs RAML, Cloud Contract (20)

Mais de Takuya Iwatsuka

Mais de Takuya Iwatsuka (9)

Último

Último (12)

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