OpenAPIによるスキーマ駆動開発を実現するための道のり

Slide 1

Slide 1 text

Slide 2

Slide 2 text

Copyrights(c) Henry, Inc. All rights reserved. 自己紹介略歴    音声認識の会社にて自然言語処理の R&Dエンジニアとして務めた後、株式会社ビズリーチへ転職し、複数のサービス開発のリードやプロジェクト管理、エンジニア採用などを経験。 2021年からヘンリーに参画。  StrengthsFinder    1. 学習欲  2. 個別化  3. 包含  4. 最上志向  5. アレンジ 

Slide 3

Slide 3 text

Slide 4

Slide 4 text

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Copyrights(c) Henry, Inc. All rights reserved. Contract-first vs. Code-first 予約システム  名簿システム  検査報告システム  Henry  Integration API  外部サービスベンダー様と協業する際のワークフローを考慮 ● 要求の認識合わせ ● APIの仕様のフィックス ● 各自が実装 ● 結合テスト ● リリース

Slide 8

Slide 8 text

Slide 9

Slide 9 text

Copyrights(c) Henry, Inc. All rights reserved. OpenAPI vs. GraphQL vs. gRPC ● 自動生成ツールチェーン周りのエコシステムが充実し、カスタマイズをそれほど多く行わなくてもいい。   ● 外部サービスと連携する部分のプロトコルなので、社内で蓄積されているナレッジはあくまで考慮要素の一つで、世の中のノウハウの充実さが非常に重要である。  

Slide 10

Slide 10 text

Copyrights(c) Henry, Inc. All rights reserved.   gRPC  GraphQL  OpenAPI  自動生成  First Party  GraphQL Code Generator  OpenAPI Generator  Swagger Codegen  利用ノウハウ  社内にはあるが、世の中ではまだそれ程多くない      OpenAPI vs. GraphQL vs. gRPC

Slide 11

Slide 11 text

Slide 12

Slide 12 text

Slide 13

Slide 13 text

Copyrights(c) Henry, Inc. All rights reserved. OpenAPI Generatorプロジェクトの全体像を把握 2018年、Swagger Codegen バージョン2.4からフォークされたコミュニティ駆動のOSSプロジェクト    その歴史については @NAKANO_Akihitoさんのスライド「平静を保ち、コードを生成せよ〜 OpenAPI Generator誕生の背景と軌跡〜」をご参照ください。 

Slide 14

Slide 14 text

Slide 15

Slide 15 text

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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を活用する

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

Slide 23

Slide 23 text

Copyrights(c) Henry, Inc. All rights reserved. 自作テンプレートの活用協力会社へ提供するAPIとはいえ、外部向けのAPIサーバーなので、入力に対するバリデーションが必要。ソースコード（modules/openapi-generator/src/main/resources/kotlin-server/libraries/ktor）内で確認したら確かにuseBeanValidationの記述がなかった（非サポートだった）

Slide 24

Slide 24 text

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) 

Slide 25

Slide 25 text

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

Slide 28

Slide 28 text

Copyrights(c) Henry, Inc. All rights reserved. Generator自作の道へ Gradleプロジェクトの完全Kotlin DSL化やフレームワークをKtor2へバージョンアップするために、自作テンプレでバッチを当て続けることの限界を感じ始めている。 KotlinServerCodegen BeanValidationFeatures AbstractKotlinCodegen DefaultCodegen CodegenConfig KotlinKtor2CodegenKt 完全自作が大変なので、なるべく既存の基底クラスの恩恵を受けつつカスタマイズしたい (Java Interopが本領発揮)

Slide 29

Slide 29 text

Copyrights(c) Henry, Inc. All rights reserved. まとめ • PRO: 仕様を簡単に作成でき、それを持って協力会社と認識合わせ・同時開発するワークフローを実現できている。 • PRO: カスタマイズ性が高く、既存機能に満足できない場合でも自作で問題解決を実現できる。 • CON: 幅広い言語と機能へ対応しているため、逆にKotlin関係のメンテナンスが遅れたりする。 • CON: ドキュメントを読んでもやり方がわからないケースが少なくないため、ソースコードまで調べなければいけない場合がある。

Slide 30

Slide 30 text