🔖
Railsのレスポンスの型をカジュアルに検証したい
やりたいこと
- 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を、更にtsのinterfaceに変換する
というわけで、出力した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の型検証はこれで必要十分だと思う。
Discussion