swagger-typescript-apiを使ってスキーマ駆動開発

今までRESTのプロジェクトでは、自前でapiのリクエスト・レスポンスのインターフェースを書いていたこともあり、apiの変更が発生した時は、都度変更したり、間違った型を書いてしまったりとこれはまずいなと思っていました。。

その後、良い感じのコードジェネレーターツールないかなーと思って探していたらswagger-typescript-apiに出会い、最近新しいプロジェクトに導入しました。導入することでswaggerで定義されているリクエスト・レスポンスの型を自動的に生成して型安全に開発を進めることができています。

そこで今回は、swagger-typescript-apiを使いapiの型を自動生成するまでの流れをご紹介します。

nodeでapi型定義ファイル生成までの処理を書く

1. open apiのファイルをダウンロード
2. 1でダウンロードしたファイルを.tsに変換する

上記の一連の処理を書いたものが以下になります。
アクセス先のurlやtokenなどは、各自のものをお使いください。

const fs = require("fs");
const path = require("path");
const axios = require("axios");
const { generateApi } = require("swagger-typescript-api");

(async () => {
  try {
    const directory = "./types/api";
    const downloadedFileName = "project-openapi.yaml";
    const generatedTypeFileName = "generatedTypes.ts"

    const { data } = await axios.get(
      "path/url to swagger scheme",
      {
        headers: {
          "PRIVATE-TOKEN": "your private token",
        },
        responseType: "text",
      },
    );

    fs.writeFileSync(`${directory}/${downloadedFileName}`, data);

    const generatedTypes = await generateApi({
      name: `${generatedTypeFileName}`,
      input: path.resolve(directory, downloadedFileName),
      generateClient: false,
    });

    fs.writeFileSync(
      `${directory}/${generatedTypeFileName}`,
      generatedTypes,
    );
  } catch (err) {
    console.error("Error:", err);
  }
})();

gitlabにあるopen apiのファイルをダウンロードしてきています。

const { data } = await axios.get(
  "path/url to swagger scheme",
  {
    headers: {
      "PRIVATE-TOKEN": "your private token",
    },
    responseType: "text",
  }
);

fs.writeFileSync(`${directory}/${fileName}`, data);

swagger-typescriptが提供しているgenerateApiを使ってyamlを元にtsファイルを生成しています。
nameの部分には、生成後のファイル名を定義しています。

const generatedTypes = await generateApi({
  name: `${generatedTypeFileName}`,
  input: path.resolve(directory,
  generateClient: false,
});

fs.writeFileSync(`${directory}/${generatedTypeFileName}`, generatedTypes);

node 上記で作成したファイル

実際にプロジェクトに使っているものでありファイルの中身は見せることができませんが、ファイルが生成されました。

後はプロジェクトに合わせてpackage.jsonにコード生成用のscriptを登録してあげるなどしてみてください。

今までgraphqlのプロジェクトでは、graphql-code-generatorを使用していたのですが、RESTでもこのようにswaggerのschemeを元にtypescriptに型を自動生成することができました。
あっという間に導入することができたので是非お試しください。