2022.11.30

スキーマ駆動開発ハンズオンを実践する

tanesan

本記事では、スキーマ駆動開発（SDD）をハンズオン的に実践してみます。
流れとしては下記の通りです

StoplightでAPIを定義
Prismでモッキング
OpenAPI Generatorでクライアントコード生成（今回はTypeScriptを使用）
生成されたコードを使ってサンプルコード作成

Contents

スキーマ駆動開発（SDD）とは
SDDハンズオン

スキーマ駆動開発（SDD）とは

API定義を初めに行い、定義されたAPIの仕様をもとにフロントエンド・バックエンドの実装を進める開発手法をスキーマ駆動開発（SDD）と言います。API定義のデファクトスタンダードであるOpen APIには豊富な周辺ツールが存在し、クライアントサイド・サーバサイドのコードの自動出力やモッキング等を簡単に行うことができます。SDDに則り開発を進めることで、これらのツールの恩恵を受けることができ開発スピードの向上が期待できます。

SDDハンズオン

1. StoplightでAPI定義

今回のハンズオンではAPI定義にStoplightを使用します。
StoplightではOpenAPIの定義をGUI上で行うことができ、OpenAPIの記述方法を学ぶことなく簡単にAPI定義をすることができます。

準備

Stoplightはブラウザ・クライアントアプリの二種類の実行方法を選ぶことができます。今回はクライアントアプリを利用します。
こちらからクライアントアプリをダウンロード・インストールしてください。

Stoplightでは、リポジトリを連携することができます。Stoplight上で変更を完結できるの連携しておくと便利です。
このハンズオンではapi-scheme-practiceというリポジトリを作成し、この中で作業します。

環境
Node.js v18.12.1
yarn v1.22.10

API作成

APIを作成していきます。gitのリポジトリを連携するとprojectとしてホーム画面右に表示されるはずです。プロジェクトをクリックしプロジェクトの画面に移動します。
プロジェクト画面に移動後、「Create」にある「API」ボタンをクリックします。その後、API作成ダイアログが出るので、API名を入力し「Create」ボタンをクリックし作成します（画像参照）。API作成が成功していれば、referenceディレクトリ配下に指定したAPI名.yamlの形で作成されます。

image.png (89.4 kB)

API作成後はデフォルトでUserエンドポイントが追加されています（画像参照）。今回は自前でAPIを実装せず、このUserエンドポイントを使用することにします。

image.png (35.5 kB)

右上のボタンでフォーム入力・コード入力を切り替えることができ、直接yamlを編集することができます。実際の開発時は変更の規模に合わせて使い分けて利用する感じにななります。また、大規模な修正が必要になる場合はStoplightではなく、その他エディターで編集作業を行なった方が効率が良い場合もあるので、そこは臨機応変に対応する必要があります。

image.png (202.6 kB)

2. Prismでモッキング

Stoplightが提供しているPrismというパッケージを使用して、前節で作成した APIをモッキングします。

こちらを参考にインストールします。

インストール

yarn global add @stoplight/prism-cli

実行

下記コマンドを実行するとAPI定義をもとにサンプルレスポンスを返すモックサーバを開始できます。

prism mock reference/api-scheme-practice.yaml

実行結果

[21:34:05] › [CLI] …  awaiting  Starting Prism…
[21:34:05] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/users/77
[21:34:05] › [CLI] ℹ  info      PATCH      http://127.0.0.1:4010/users/655
[21:34:05] › [CLI] ℹ  info      POST       http://127.0.0.1:4010/user
[21:34:05] › [CLI] ▶  start     Prism is listening on http://127.0.0.1:4010

Stoplightで定義したエンドポイントがホストされていることがわかります。

動作確認

PrismではOpenAPIのExampleタグで定義したオブジェクトをモックのレスポンスとして返すことができます。Stoplightだと画像の位置で定義することができます。

image.png (47.3 kB)

上記画像にある「Get User Alice Smith」レスポンスが返ってくるか下記コマンドで確認します。

curl -X GET 'http://localhost:4010/users/836'

実行結果

{"id":142,"firstName":"Alice","lastName":"Smith","email":"alice.smith@gmail.com","dateOfBirth":"1997-10-31","emailVerified":true,"signUpDate":"2019-08-24"}%

このような感じで簡単にモッキングすることが可能です。

3. OpenAPI Generatorでクライアントコード生成

OpenAPI Generatorを使ってOpenAPIのyamlファイルからクライアントコードを出力します。

インストール

まず下記コマンドでopenapi-generatorをインストールします。

npm install @openapitools/openapi-generator-cli

また、openapi-generatorの実行にはjavaが必要なのでこちらを参考にインストールしてください

クライアントコード出力

下記のコマンドを実行し、typescriptのクライアントコードを出力します。

npx @openapitools/openapi-generator-cli generate -g typescript-fetch -i reference/api-scheme-practice.yaml -o out/ --additional-properties=typescriptThreePlus=true

今回はfetchを使ったクライアントコードを作成するために-gオプションで「typescript-fetch」を指定しています。また、デフォルトだと古いバージョンのTypeScriptのコードが出力されるので「 --additional-properties=typescriptThreePlus=true」を付け加えています。

正常にコマンドが実行できていれば、outディレクトリ配下にクライアントコードが自動出力されます。

4. 生成されたコードを使ってサンプル作成

TypeScriptでモックサーバにAPIリクエストするサンプルコードを作成します。

準備

TypeScriptを実行するために下記コマンドを実行します

npx tsc --init

サンプルコード

今回使用するサンプルコードです。

import { DefaultApi } from './out/apis/DefaultApi';

const conf = new Configuration({
  basePath: 'http://127.0.0.1:4010',
})
const client = new DefaultApi(conf)

const getUser = async () => {
  return await client.getUsersUserId({ userId:'77' })
}

getUser().then((res) => {
  console.log(res)
})

デフォルトだとyamlファイルのserversタグにあるurlに接続しにいってしまうので、Prismで立ち上げたモックサーバに接続できるようにConfigurationを作成しています。

実行

下記のコマンドでサンプルコードを実行

npx ts-node sample.ts

実行結果
正しく実行できていれば、Prismの動作確認時と同じ、「Get User Alice Smith」で定義したサンプルレスポンスが取得できるはずです。

{
  id: 142,
  firstName: 'Alice',
  lastName: 'Smith',
  email: 'alice.smith@gmail.com',
  dateOfBirth: '1997-10-31',
  emailVerified: true,
  createDate: undefined
}