Zenn
🐬

swagger-typescript-apiを用いたAPIクライアントの自動生成

2023/09/01に公開
TypeScript
SWR
Swagger
axios
OpenAPI
tech

概要:Summary

  • swaggerから自動生成したコードを使ってAPIクライアントを作成します。swagger-typescript-apiを筆頭に、SWR, axiosなどのライブラリを併用します。
    swagger-typescript-api
    SWR
    axios

利点:Advantage

  • コードがシンプルになり可読性が上がります。
  • API接続をより感覚的に行えるようになります。

例:Examples

  • 以下のように短いコードでAPI接続が可能になります。
const fetcher = async () => {
  const response = await api.hogehoge.hogehogeList();
  return response.data;
};
const { data, error, isLoading } = useSWR({}, fetcher);

実装

  • 手順には複数のやり方が存在します。今回は私が用いた方法のみを解説します。詳しくは各ドキュメントを参照してください。

OpenAPIスキーマから型を自動生成

  • OpenAPIスキーマを用意します。
  • axiosを用いての実装となります。
    • axiosはnode.jsのpromiseベースのhttpクライアントです。
  • 必ずoptionsにaxiosをつけてください。
  • cliから以下を実行
npx swagger-typescript-api --axios -p ファイルのパスを指定 -o 自動生成先の場所指定 -n 自動生成のファイル名
  • 例:example
npx swagger-typescript-api --axios -p ./index.yaml -o ./src/_generated -n API.ts
  • ファイルが自動生成されました
  • 主に使うもの
    • 型：リクエストやレスポンス、エラーの型が生成されています。
    • Apiクラス：httpリクエストが具体的なエンドポイントごとに定義されています。このApiクラスを用いて、APIクラアントを実装していきます。

APIクライアントのセットアップ

  • エンドポイントの共通部分やインスタンスの作成、レスポンスインターセプターの設定を行います。
  • 例:example
import { Api } from 'src/_generated/API';
import { BASE_URL } from 'src/config-global';

// ----------------------------------------------------------------------

export const api = new Api({
  baseURL: BASE_URL,
});
const axiosInstance = api.instance;
axiosInstance.interceptors.response.use(
  (response) => response,
  (error) => Promise.reject((error.response && error.response.data) || 'Something went wrong')
);

export default axiosInstance;
  • BASE_URLは環境変数として管理すると便利です。
  • ここで作成したaxiosInstanceに認証情報を付与していきます。
  • ここで作成したapiを呼び出して、各APIを接続していきます。

認証情報とaxios

  • 今回私は認証情報をContextで管理しました。
  • 先ほど設定したaxiosInstanceをimportしてください。
  • お使いのAPI独自のheaderは2行目以降にあるExampleの部分を変更してください。
axiosInstance.defaults.headers.common.Authorization = `Bearer ${token}`;
axiosInstance.defaults.headers.common['Example'] = 'Example';
axiosInstance.defaults.headers.common['Example2'] = 'Example2';

APIクライアントの実装

  • 今回の目的であるAPIクライアントを実装します。
  • データ取得と状態管理のため、SWRを使います。
  • SWRのAPIを使います。GETにはuseSWRを、その他のメソッドにはuseSWRMutationを用います。

GETメソッド

  • 例:example
const fetcher = async () => {
  const response = await api.hogehoge.hogehogeList();
  return response.data;
};
const { data, error, isLoading } = useSWR({}, fetcher);
  • シンプルな例です。useSWR<第一引数, 第二引数>({... 第一引数にdataの型を、第二引数にエラーの型を指定することができます。
  • ご覧の通り、エンドポイントの指定等がなく、非常にシンプルなAPIクライアントが作成できます。
  • queryを渡す際は以下のように指定します。
const fetcher = async () => {
  const query = { hogehoge:hogehoge }
  const response = await api.hogehoge.hogehogeList(query);
  return response.data;
};
const { data, error, isLoading } = useSWR({}, fetcher);

PUT/POST/DELETEメソッド

  • useSWRMutationを用いて、trigger関数による発火でリクエストを送ります。
  • hogehogeRequestにリクエストの型を指定します。自動生成されたファイルに型が指定されているので確認しましょう。
  • ここで指定した型通りのリクエストをtriggerの引数に指定します。
  async function hogehoge({}, { arg }: { arg: hogehogeRequest }) {
    await api.hogehoge.hogehogeCreate(arg);
  }
  const { trigger } = useSWRMutation({}, hogehoge);
  • 以下のようにtriggerに引数を渡して発火させるとリクエストが送られます。
  • dataはhogehogeRequestの型。
trigger(data);

おわり

  • 最後まで読んでいただき感謝です！
  • みんなappsyncを使いましょう。

Discussion