Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
OpenAPIによるスキーマ駆動開発を実現するための道のり
Search
Cyan
December 12, 2022
Programming
0
1.1k
OpenAPIによるスキーマ駆動開発を実現するための道のり
Kotlin Fest Reject Conference 2022 発表資料
Cyan
December 12, 2022
Tweet
Share
More Decks by Cyan
See All by Cyan
EBMをベースに考えるプロダクト価値最大化 / Product Value Maximization Based on EBM
cho0o0
0
240
VPoEの視点から見た、ヘンリーがサーバーサイドKotlinを使う理由 / Why Server-side Kotlin 2024
cho0o0
1
820
エンジニアリング上の経験を普段のコミュニケーションにも活かせた話
cho0o0
0
190
Hatena DevBlog Meetup #1 LT
cho0o0
0
3.3k
ヘンリーのコミュニケーションスケーリング戦術 ~ミーティング編~
cho0o0
1
270
ファシリテーション勉強会
cho0o0
0
170
Token Ringについて
cho0o0
1
1.1k
仕様ワークショップ
cho0o0
0
110
Introduction to ATDD (ATDD入門)
cho0o0
0
90
Other Decks in Programming
See All in Programming
2分台で1500examples完走!爆速CIを支える環境構築術 - Kaigi on Rails 2025
falcon8823
3
3.3k
monorepo の Go テストをはやくした〜い!~最小の依存解決への道のり~ / faster-testing-of-monorepos
convto
2
400
止められない医療アプリ、そっと Swift 6 へ
medley
1
120
ИИ-Агенты в каждый дом – Алексей Порядин, PythoNN
sobolevn
0
150
2025年版 サーバーレス Web アプリケーションの作り方
hayatow
23
25k
Catch Up: Go Style Guide Update
andpad
0
180
株式会社 Sun terras カンパニーデック
sunterras
0
230
フロントエンド開発に役立つクライアントプログラム共通のノウハウ / Universal client-side programming best practices for frontend development
nrslib
7
3.9k
Go言語の特性を活かした公式MCP SDKの設計
hond0413
1
180
CSC509 Lecture 01
javiergs
PRO
1
430
プログラマのための作曲入門
cheebow
0
540
ポスターセッション: 「まっすぐ行って、右!」って言ってラズパイカーを動かしたい 〜生成AI × Raspberry Pi Pico × Gradioの試作メモ〜
komofr
0
960
Featured
See All Featured
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
333
22k
GitHub's CSS Performance
jonrohan
1032
460k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
29
2.6k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
PRO
188
55k
Into the Great Unknown - MozCon
thekraken
40
2.1k
Building Better People: How to give real-time feedback that sticks.
wjessup
368
20k
How to Think Like a Performance Engineer
csswizardry
27
2k
The Straight Up "How To Draw Better" Workshop
denniskardys
237
140k
A Modern Web Designer's Workflow
chriscoyier
697
190k
Building Adaptive Systems
keathley
43
2.8k
Principles of Awesome APIs and How to Build Them.
keavy
127
17k
How STYLIGHT went responsive
nonsquared
100
5.8k
Transcript
Copyrights(c) Henry, Inc. All rights reserved. OpenAPIによる スキーマ駆動開 発を実現するため の道のり
張 @shenyu_cyan
Copyrights(c) Henry, Inc. All rights reserved. 自己紹介 略歴 音声認識の会社にて自然言語処理の
R&Dエンジニアとして務めた 後、株式会社ビズリーチへ転職し、複数のサービス開発のリードやプ ロジェクト管理、エンジニア採用などを経験。 2021年からヘンリーに 参画。 StrengthsFinder 1. 学習欲 2. 個別化 3. 包含 4. 最上志向 5. アレンジ
Copyrights(c) Henry, Inc. All rights reserved. アジェンダ • WHY なぜOpenAPIによるスキーマ駆動開発を使うべきと判断し
たのか • Contract-first vs. Code-first • OpenAPI vs. GraphQL vs. gRPC • WHAT サーバーサイドKotlinでスキーマ駆動開発を実現するため の守破離
Copyrights(c) Henry, Inc. All rights reserved. Contract-first vs. Code-first 予約システム
名簿システム 検査報告システム Henry Integration API
Copyrights(c) Henry, Inc. All rights reserved. Contract-first vs. Code-first OpenAPI
Specification (OAS) Kotlin
Copyrights(c) Henry, Inc. All rights reserved. Contract-first vs. Code-first OpenAPI
Specification (OAS) Kotlin e.g. SpringFox / SpringDoc
Copyrights(c) Henry, Inc. All rights reserved. Contract-first vs. Code-first 予約システム
名簿システム 検査報告システム Henry Integration API 外部サービスベンダー様と協業する際のワークフローを 考慮 • 要求の認識合わせ • APIの仕様のフィックス • 各自が実装 • 結合テスト • リリース
Copyrights(c) Henry, Inc. All rights reserved. Contract-first vs. Code-first
Copyrights(c) Henry, Inc. All rights reserved. OpenAPI vs. GraphQL vs.
gRPC • 自動生成ツールチェーン周りのエコシステムが充実し、カスタマイズをそれほど多く行わなくてもいい。 • 外部サービスと連携する部分のプロトコルなので、社内で蓄積されているナレッジはあくまで考慮要素の一つで、世 の中のノウハウの充実さが非常に重要である。
Copyrights(c) Henry, Inc. All rights reserved. gRPC GraphQL OpenAPI
自動生成 First Party GraphQL Code Generator OpenAPI Generator Swagger Codegen 利用ノウハウ 社内にはあるが、世の中で はまだそれ程多くない OpenAPI vs. GraphQL vs. gRPC
Copyrights(c) Henry, Inc. All rights reserved. スキーマ駆動開発を実現する為に 守 破 離
Copyrights(c) Henry, Inc. All rights reserved. スキーマ駆動開発を実現するための守 • OpenAPI Generatorプロジェクトの全体像を把握
• Gradleプロジェクトで使うための設定方法 守
Copyrights(c) Henry, Inc. All rights reserved. OpenAPI Generatorプロジェクト の全体像を把握 2018年、Swagger
Codegen バージョン2.4からフォークされた コミュニティ駆動のOSSプロジェクト その歴史については @NAKANO_Akihitoさんのスライド「平静を 保ち、コードを生成せよ 〜 OpenAPI Generator誕生の背景と 軌跡 〜」をご参照ください。
Copyrights(c) Henry, Inc. All rights reserved. OpenAPI Generatorプロジェクト の全体像を把握 openapi-generator
実行可能なJARプログラム OpenAPI Generatorのインタフェース Gradle Plugin メインの実装
Copyrights(c) Henry, Inc. All rights reserved. OpenAPITools Bazelのプラグイン CLIのNode ラッパー
sbtのプラグイン OpenAPI Generatorプロジェクト の全体像を把握
Copyrights(c) Henry, Inc. All rights reserved. openapi-generator-core openapi-generator openapi-generator-cli openapi-generator-
gradle-plugin sbt-openapi-generator openapi-generator-cli (Node Wrapper) OpenAPI Generatorプロジェクト の全体像を把握 Henryのサーバーサイドアプリは Kotlin+Gradleに統一している為、 こちらだけ意識すれば OK
Copyrights(c) Henry, Inc. All rights reserved. Gradleプロジェクトで使うための 設定方法 openapiプロジェクトを利用した実装モジュール Generatorによって生成されたモジュール
OpenAPIの定義ファイル マルチモジュール構造のプロジェクト ワークフロー 1. spec.ymlにてRestful APIの定義を行う 2. OpenAPI Generator Gradle Pluginを利 用して、Gradleタスクを実行することでエ ンドポイントとDTOのKotlinコードを自動作 成 (openapiモジュール) 3. 実装(app)モジュールにて自動生成され たエンドポイントのインタフェースを継承 し、DTOを活用する
Copyrights(c) Henry, Inc. All rights reserved. Gradleプロジェクトで使うための 設定方法 include("app") include("openapi")
Copyrights(c) Henry, Inc. All rights reserved. Gradleプロジェクトで使うための 設定方法 dependencies {
… implementation(project(":openapi")) }
Copyrights(c) Henry, Inc. All rights reserved. Gradleプロジェクトで使うための 設定方法
Copyrights(c) Henry, Inc. All rights reserved. Gradleプロジェクトで使うための 設定方法 *設定例として抜粋 Gradleプラグインの設定
ジェネレーター設定 テンプレートの設定
Copyrights(c) Henry, Inc. All rights reserved. スキーマ駆動開発を実現するための破 • 自作テンプレートの活用 •
複数の定義ファイルへの対応 破
Copyrights(c) Henry, Inc. All rights reserved. 自作テンプレートの活用 協力会社へ提供するAPIとはいえ、外部向けのAPIサーバーなので、 入力に対するバリデーションが必要。 ソースコード(modules/openapi-generator/src/main/resources/kotlin-server/libraries/ktor)内で確認
したら確かにuseBeanValidationの記述がなかった(非サポートだった)
Copyrights(c) Henry, Inc. All rights reserved. 自作テンプレートの活用 User-defined Templatesを利用すれば、既存のテンプレートを簡単に オーバーライドできる。
• build.gradle.ktsのopenApiGenerate設定に自作テンプレの場所を 指定 templateDir.set("$rootDir/openapi/templates") • テンプレを作成し、オーバーライドしたいファイルのテンプレ名と同 じ名前のファイルとして上記のフォルダに格納する AppMain.kt→AppMain.kt.mustache build.gradle→build.gradle.mustache 弊社では、BeanValidatation以外に、ロギングやデータマスキングのた めに自作テンプレートを活用している。 OpenAPI Generator Gradle Plugin KotlinServerCodegen (org.openapitools.codegen.languag es.KotlinServerCodegen) Default Templates (modules/openapi-generator/src/m ain/resources/kotlin-server/libraries /*.mustache) Kotlin Code (openapi/*.kt)
Copyrights(c) Henry, Inc. All rights reserved. 複数の定義ファイルへの対応 対応するAPIが増えることによって、全てのAPI定義を一つのファイル にまとめることは書きづらさ、メンテナンスしにくさに直結してしまう。 spec.yml
Kotlinコード spec.x.yml spec.y.yml spec.z.yml spec._base.yml
Copyrights(c) Henry, Inc. All rights reserved. 複数の定義ファイルへの対応 • @alexlafroscia/yaml-merge(NPMライブラリ)を使って定義ファイルのマージを行う •
Frontend Gradle Plugin (org.siouan.frontend-jdk11)を使ってGradleタスクとして定義 • GradleタスクopenApiGenerateの依存関係(dependsOn)に定義ファイルマージのGradleタスク を追加 spec.yml Kotlinコード spec.x.yml spec.y.yml spec.z.yml spec._base.yml
Copyrights(c) Henry, Inc. All rights reserved. スキーマ駆動開発を実現するための離 Generator自作の道へ 離
Copyrights(c) Henry, Inc. All rights reserved. Generator自作の道へ Gradleプロジェクトの完全Kotlin DSL化やフレームワークをKtor2へ バージョンアップするために、自作テンプレでバッチを当て続けること
の限界を感じ始めている。 KotlinServerCodegen BeanValidationFeatures AbstractKotlinCodegen DefaultCodegen CodegenConfig KotlinKtor2CodegenKt 完全自作が大変なので、なるべく 既存の基底クラスの恩恵を受け つつカスタマイズしたい (Java Interopが本領発揮)
Copyrights(c) Henry, Inc. All rights reserved. まとめ • PRO: 仕様を簡単に作成でき、それを持って協力会社と認識合わ
せ・同時開発するワークフローを実現できている。 • PRO: カスタマイズ性が高く、既存機能に満足できない場合でも自 作で問題解決を実現できる。 • CON: 幅広い言語と機能へ対応しているため、逆にKotlin関係のメ ンテナンスが遅れたりする。 • CON: ドキュメントを読んでもやり方がわからないケースが少なくな いため、ソースコードまで調べなければいけない場合がある。
Copyrights(c) Henry, Inc. All rights reserved. 医療DX 難しい課題の解決 社会貢献 これらのキーワードが気になる方
一度カジュアルにお話ししましょう We are Hiring ! https://jobs.henry-app.jp/