🔖

Railsのレスポンスの型をカジュアルに検証したい

2022/09/06に公開

Rails

jsonschema

TypeScript

tech

やりたいこと

Railsで実装しているAPIのAPIDocが何も無く、frontend側の実装がつらい
というわけでAPIのレスポンスの型を検証したい
型情報は簡単に書きたい
OpenAPIのymlは絶対に書きたくない
飽くまでAPIのレスポンスの型を静的に知りたいだけで、APIのスペックが欲しいわけではない
検証に使った型はクライアント側でも使いたい (今回はTypeScriptを想定)
型の情報のマスターデータはきちんとサーバ側で持ちたい

サンプル

例えばサーバ側に Book というモデルがあり、それを返すAPIがあるとする

1. TypeScriptで型を作る

型はやはり馴染みがある言語で書きたい。

interface BookApiResponse {
  title: string;
  pages: number;
  published: boolean
}

2. typescrit-json-schemaでTypeScriptの型をJsonSchemaに変換する

さすがにtsそのままではrubyからは使えないので、何か一般的なフォーマットに変換する必要がある。

$ yarn typescript-json-schema book_api_response.ts BookApiResponse > schema.json

これで↓な感じのJsonSchemaが出力できる

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
        "pages": {
            "type": "number"
        },
        "published": {
            "type": "boolean"
        },
        "title": {
            "type": "string"
        }
    },
    "type": "object"
}

3. rubyのjson-schemaを使い、APIのレスポンスの型を検証

先ほど出力したJsonSchemaを使い、APIのレスポンスのjsonが期待通りか↓のような感じで検証出来る。

JSON::Validator.validate('schema.json', response.body)

4. 出力したJsonSchemaを、更にｔｓのinterfaceに変換する

マスターデータは飽くまでサーバ側に寄せたいので、最初に作ったtsのファイルをそのまま使うのは避けたい。
というわけで、出力したJsonSchemaから更にTypeScriptの型ファイルを生成する。

これで↓な感じのtsのinterfaceが出力できる

/* tslint:disable */
/**
 * This file was automatically generated by json-schema-to-typescript.
 * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
 * and run json-schema-to-typescript to regenerate this file.
 */

export interface BookApiResponse {
  pages?: number;
  published?: boolean;
  title?: string;
  [k: string]: unknown;
}

自分で書かないといけないのはTypeScriptのinterfaceだけであとは変換を重ねるだけなのでとても楽。
社内でしか使っていないようなAPIの型検証はこれで必要十分だと思う。