TypeScript REST APIクライアント

TypeScript (WebpackもしくはNode.js) で利用できるREST APIクライアントライブラリを調査した。

まとめ

• axiosとtyped-rest-clientがユーザー数が多く、開発も安定している。
  • 2019年11月時点ではaxiosの方が人気があるが、typed-rest-clientはTypeScript本家のMicrosoftがメンテしているため、デファクトになっていく可能性あり。
• Web標準的にはFetch APIだが、現時点ではブラウザサポートが不完全であり、TypeScriptで型を利用する部分は自力で実装する必要がある。
  • ブラウザサポートについてはPolyfillライブラリを使う手もある。
• Open API（Swagger）形式の仕様書がある場合はOpenAPI GeneratorでクライアントSDKを生成すると効率がよい。
  • OpenAPI GeneratorはSwagger Codegenをフォークしてコミュニティ主体で開発をしているもの。Swagger Codegenよりも開発が活発でGeneratorの種類も多い。（参考：Swagger Codegen Fork: Q&A）
  • TypeScript用Generatorには、typescript-axios、typescript-fetchや、typescript-anglarなどのフレームワーク向けのものもある。（参考：Generators List）

ライブラリの利用例

OpenAPI Generator

クライアントSDK生成

CLIツールはNPMやDockerイメージなど多様な形式でインストールできる。（参考：CLI Installation）

フレームワークに依存しないGeneratorには、axiosとfetchを使うものがあったが、上述の理由から前者のtypescript-axiosを選択した。以下のコマンドでプロジェクトのsrcディレクトリにクライアントSDKを出力する。

openapi-generator-cli generate -g typescript-axios -i ./openapi.yaml -o ./src/client-axios

SDKを利用したAPI呼び出し

OpenAPI仕様書に記載されるURLと実際の接続先が異なる場合は、コンストラクタのbasePathパラメータにベースURLを指定すればよい。

import { DefaultApi } from '@/client-axios';

const baseUrl = 'https://jsonplaceholder.typicode.com';
new DefaultApi({ basePath: baseUrl }).getToDo(1).then((res) => {
  console.log(res.data);
})

なお、出力コードがプロジェクトのLint設定と合わない場合は、検証対象外に入れておく。

# .eslintignore
src/client-axios

また、出力コード中でNode.jsのurlモジュールが使われているため、Webpack環境で型定義を webpack-env に限定している場合は、Node.jsモジュールの型定義も参照できるようにする必要がある。（参考：TypeScript設定リファレンス）

// tsconfig.json
{
  "compilerOptions": {
    "types": ["webpack-env", "node"]
  }
}

axios

レスポンスボディの型をinterfaceとして定義して型パラメータに指定すればよい。

interface Todo {
  userId: number,
  id: number,
  title: string,
  completed: boolean,
}

import axios from 'axios';

const url = 'https://jsonplaceholder.typicode.com/todos/1';
axios.get<Todo>(url).then((res) => {
  console.log(res.data);
});

参考

• OpenAPIからクライアントを作成する方法
  • OpenAPIとTypeScriptで作る！チーム開発に適したWebアプリケーションの作り方
  • OpenAPI GeneratorでRESTful APIの定義書から色々自動生成する
• Vue.jsクックブック
  • Fetch APIにはまだ問題が残っているため、axiosを推奨している。