APIクライアントとスタブAPIサーバーのプログラムを自動生成して、疎通確認をする
はじめに
今回はAPIクライアントとスタブAPIサーバー（以下、スタブサーバー）のプログラムを自動生成して、
疎通確認を行います。プログラムの自動生成にはOpenAPI Generatorを使います。
APIクライアントは、Create React Appで作成するプロジェクトに導入します。
スタブサーバーは、なるべく手間をかけずにローカルに立てる方針で進めていきたいと思います。
環境
- Windows10
- Node.js v14.16.0
- npm v6.14.11
- Yarn 1.22.10
プロジェクトを作成する
下記のコマンドを実行して、「react-openapi-sample」という名前のReact+TypeScriptのプロジェクトを作成します。
npx create-react-app react-openapi-sample --template=typescript
プロジェクトの作成後、プロジェクト直下に移動します。
cd react-openapi-sample
APIを定義したYAMLを作成する
今回はAPIを１つだけ定義した下記のYAMLを使います。
「openapi.yaml」と名前を付けてプロジェクト直下に保存します。
OpenAPI Generatorは、このYAMLからプログラムを自動生成します。
openapi: 3.0.3
info:
title: サンプルAPI
version: 1.0.0
servers:
- url: http://localhost:8080
description: stub API server
tags:
- name: fruit
paths:
/fruits:
get:
tags:
- fruit
description: フルーツの一覧を取得する
operationId: getFruits
responses:
'200':
$ref: '#/components/responses/GetFruitsResponse'
components:
schemas:
Fruit:
type: object
description: フルーツ
properties:
id:
description: ID
type: integer
example: 1
name:
description: 名前
type: string
example: リンゴ
producing_area:
description: 生産地
type: string
example: 青森県
required:
- id
- name
- producing_area
Fruits:
type: object
description: フルーツの一覧
properties:
fruits:
type: array
items:
$ref: '#/components/schemas/Fruit'
required:
- fruits
responses:
GetFruitsResponse:
description: /fruitsのレスポンス
content:
application/json:
schema:
$ref: '#/components/schemas/Fruits'
詳しいAPIの定義方法については、OpenAPI Specificationをご参照ください。
OpenAPI Generatorをインストールする
下記のコマンドを実行して、OpenAPI Generatorをインストールします。
yarn add @openapitools/openapi-generator-cli -D
APIクライアントのプログラムを自動生成する
下記のコマンドを実行して、APIクライアントのプログラムを自動生成します。
今回は自動生成するプログラムとして、TypeScriptかつ追加ライブラリが不要なFetch APIを指定しています。
併せてTypeScript v3.6以降と互換性のあるプログラムを生成するため、オプションに「-p typescriptThreePlus=true」を指定しています。
"node_modules/.bin/openapi-generator-cli" generate -i openapi.yaml -g typescript-fetch -p typescriptThreePlus=true -o src/openapi
-i：APIを定義したYAMLのパス
-g：自動生成するプログラム
-p：自動生成するプログラムのオプション設定
-o：プログラムの出力先
自動生成したAPIクライアントのプログラムを導入する
src/App.tsxを開き、以下の通り修正します。
import React, {useState} from 'react';
import {Fruit, FruitApi} from './openapi'; // OpenAPI Generatorで自動生成したプログラムをインポートする
function App() {
const [fruits, setFruits] = useState([] as Fruit[]);
const onClickHandler = async () => {
// スタブサーバーにリクエストを送信し、レスポンスを受け取る
const response = await new FruitApi().getFruits();
// レスポンスをコンポーネントに反映する
setFruits(response.fruits);
};
return (
<div className="App">
<div style={{width: 'fit-content', margin: '10px auto'}}>
<button onClick={onClickHandler}>疎通確認</button>
</div>
<table style={{margin: '0 auto'}}>
<caption style={{minWidth: '130px'}}>フルーツの一覧</caption>
<thead>
<tr>
<th>ID</th>
<th>名前</th>
<th>生産地</th>
</tr>
</thead>
<tbody>
{fruits.map(fruit => {
const {id, name, producingArea} = fruit;
return (
<tr key={id}>
<td>{id}</td>
<td>{name}</td>
<td>{producingArea}</td>
</tr>
);
})}
</tbody>
</table>
</div>
);
}
export default App;
フロントエンドのプログラムを実行する
下記のコマンドを実行して、Create React Appに組み込まれている開発用のサーバーを起動します。
yarn start
起動に成功すると以下の画面が表示されます。
スタブサーバーを構築する
ここからは、スタブサーバーをローカルに構築していきます。
先の手順で作成したプロジェクト直下で、新しくコマンドラインを開きます。
スタブサーバーのプログラムを自動生成する
下記のコマンドを実行して、スタブサーバーのプログラムを自動生成します。
今回は手間をかけずにサーバーを立てるため、Node.jsがインストール済みの環境で動かせる「nodejs-express-server」を選択します。
"node_modules/.bin/openapi-generator-cli" generate -i openapi.yaml -g nodejs-express-server -o stub-server
-i：APIを定義したYAMLのパス
-g：自動生成するプログラム
-o：プログラムの出力先
サーバープログラムに必要なライブラリをインストールする
プログラムの自動生成後、出力先として指定したフォルダに移動します。
cd stub-server
下記のコマンドを実行して、必要なライブラリをインストールします。
yarn install
レスポンスとして返すJSONデータを定義する
下記のJSONデータをレスポンスとして使います。
stub-dataフォルダを作成して、フォルダ内に「getFruitsResponse.json」と名前を付けて保存します。
{
"fruits": [
{
"id": 1,
"name": "リンゴ",
"producing_area": "青森県"
},
{
"id": 2,
"name": "ブドウ",
"producing_area": "山梨県"
},
{
"id": 3,
"name": "メロン",
"producing_area": "茨城県"
},
{
"id": 4,
"name": "モモ",
"producing_area": "山梨県"
},
{
"id": 5,
"name": "ナシ",
"producing_area": "千葉県"
}
]
}
JSONデータをレスポンスに設定する
stub-server/services/FruitService.jsを開き、下記コード内の★付きのコメント通りに修正します。
/* eslint-disable no-unused-vars */
// ★ここから下のpath, fs, configを追加する
const path = require('path');
const fs = require('fs');
const config = require('../config');
const Service = require('./Service');
/**
* フルーツの一覧を取得する
*
* returns Fruits
* */
const getFruits = () => new Promise(
async (resolve, reject) => {
try {
// ★tryブロック内を下記の通りに修正する
const responseJsonFilePath = path.join(config.ROOT_DIR, 'stub-data', 'getFruitsResponse.json');
const response = JSON.parse(fs.readFileSync(responseJsonFilePath, 'utf8'));
resolve(Service.successResponse(response));
} catch (e) {
reject(Service.rejectResponse(
e.message || 'Invalid input',
e.status || 405,
));
}
},
);
module.exports = {
getFruits,
};
スタブサーバーを起動する
下記のコマンドを実行して、スタブサーバーを起動します。
yarn start
動作確認
フロントエンドのプログラムを実行した際に表示された画面の「疎通確認」ボタンを押下します。
ボタン押下後、スタブサーバーからレスポンスとして定義したJSONデータが返ってくることが確認できます。
まとめ
今回はOpenAPI Generatorを使い、APIクライアントとスタブサーバーのプログラムを自動生成して、
疎通確認まで行いました。今回のサンプルはシンプルな構造のJSONデータでしたが、複雑な構造だと
手で作成するのは、さすがにしんどいです。まだまだ課題はありますが、少しずつ改良して実践的に
使っていけたらいいなと思います。
