OpenAPIとPrisma 〜だらしない人でもドキュメントを残せる個人開発〜

OpenAPIとPrisma だらしない人でもドキュメントを残せる個人開 発 かたやましんいち

自己紹介 かたやましんいち 長岡市でWeb周りをやっている個人事業主 最近はもっぱらTypeScript。PHPとかフロント周りもやります。 twitter: @kt_shin1 おじいになってもコード書いていたい

内容 だらしない人間がウェブアプリを一人で開発するにあたっての課題 ちゃんとドキュメントを残したい 1年後とかに修正が来ても思い出せるようにしたい もちろん、手間は増やしたくない 開発の手間を減らしたい という人間が、OpenAPIとPrismaを使ってみた話。

ひとり開発のつらみ 一人でウェブ開発することが多いです 作るのは苦じゃないですが、メンテナンスとか運用が大変 恥ずかしながらドキュメント的なものを残すのがめんどい 最初は張り切って書いていても、納期が近くなったり面倒な修正が 入ったりすると後回しに 誰にも怒られないのでそのままに。。 そして、アップデートされていないドキュメントだけが残る 数年後に修正依頼が来て泣く

OpenAPI REST API を設計するための仕様 Prisma TypeScriptのORM がこれらの悩みを解決してくれそうだったので 使ってみました。

OpenAPIについて OpenAPIとは OpenAPI仕様（OAS）は、RESTful APIへの標準の言語に依存しな いインターフェースを定義します。これにより、人間とコンピュータ ーの両方が、ソースコード、ドキュメントにアクセスすることなく、 またはネットワークトラフィック検査を通じて、サービスの機能を検 出して理解できます。 ※Swaggerと呼ばれることもあっていろいろ経緯があるらしい...

OpenAPIとは YAMLとかJSONとかでAPIの仕様を定義する書き方 パスの定義 HTTPメソッド（GET,POST,PUT,PATCH,DELETE...） リクエストやレスポンスの定義 型、パラメータの種別（文字列、数値、配列、オブジェクト...） 制約（文字数、Email形式、UUID形式、Enums...） セキュリティ他 トークンやその形式（JWTとか）

OpenAPIの例

OpenAPIの書き方

OpenAPIの書き方

OpenAPIのいいところ 普通に設計図として見やすい エディタが豊富なので閲覧・編集が非常にラク 結構直感的にHTTPの作法に沿ってネストするだけなので学習コス ト低め ジェネレーターが豊富でいろいろなコードを自動生成してくれる

OpenAPI Generator OpenAPIからいろいろなコードを自動生成してくれるツール いいなと思ったところ TypeScript, Express, axios, PHP に対応している。（他にもい ろいろ対応しています） コードを生成するということは、それにつかうTypeScriptの型と かも自動生成してくれるのでそれを使ってコードを書けば便利そう

axiosのコードを自動生成

TypeScriptの型を自動生成

OpenAPI Validator OpenAPIをつかってサーバーサイドのバリデーションをしてくれる express-openapi-validator Express(Node.jsのウェブサーバー)のミドルウェア OpenAPI自体かなり細かく制約を設けられる一般的なのバリデー ションはこれで賄える こちらもいろいろなバリデーターがあります。

express-openapi-validator
ミドルウェアとして設定するだけ

app.use(
OpenApiValidator.middleware({
apiSpec: './openapi.yaml',
validateRequests: true, // (default)
validateResponses: true, // false by default
}),
);

リクエストとレスポンスを検証。
アップロードされた画像ファイルとかも検証できます。

導入前イメージ

導入後イメージ

便利になったこと 開発の手間が削減 リクエスト、レスポンスの型ができているので使い回せる APIリクエストは関数をよぶだけ サーバーのレスポンスを型で縛っておけば安心

あとから修正するときに便利 1. パラメータの変更があったらOpenAPIを修正する 2. タイプエラーが出たところを追いかけて修正する 3. で、だいたいカバーできる。 OpenAPIというドキュメントが常に最新の状 態で残る

データベースについて データベースの設計書の問題 これも最初は張り切って作るけど、つい、ちょこっと追加したカラ ムの影響であとで泣く OpenAPIではカバーできない

Prismaについて Prismaとは Next-generation Node.js and TypeScript ORM Prismaは、PostgreSQL、MySQL、SQL Server、SQLite、 MongoDB、CockroachDB用のオープンソースデータベースツー ルキットを使用して、アプリ開発者がより速くビルドし、エラーを 減らすのに役立ちます。 ※ 今回つかったはPrisma2らしくて1があるらしい...

Prismaのよいところ 個人的にMySQLをよく使います。 TypeScriptでのクエリの書き心地がよかった マイグレーションの仕組みがよかった テーブル定義ファイルを作成 スキーマからテーブル生成 スキーマ定義ファイルを修正すると差分をマイグレーション スキーマ定義ファイルというドキュメントが残る

スキーマ $ prisma migrate dev

テーブル users posts

マイグレーション 修正があったらスキーマ定義を上書きで修正する。 差分をマイグレーションしてくれる 常に最新のスキーマ定義ファイルが存在する状態 変更履歴もわかる 1. スキーマからマイグレーションクエリ作成 2. マイグレーション 3. クエリの履歴を追いかけると変更履歴もわかる

ポイント リレーション @relation と Post[] タイムスタンプ @updatedAt モデルとテーブル名、フィールド名 @@map @map

クエリ 呼び出して、存在しないときはエラー

クエリ 更新、データがなければ作成

クエリ 作成、リレーション先も作成

pull データベースからスキーマファイルを作る スキーマファイルからTypeScriptのクライアントを作る 2つのアプリケーションでDBを共有するとき $ prisma db pull

既存のDBに新たにアプリを追加するとき

その他便利機能 シーダー ミドルウェア カスタムバリデーター Computed fields

導入前イメージ

導入後イメージ

よかったこと Prismaのスキーマファイルが、そのままDBのドキュメントになる DBからは取得した値が型定義される DBからは取得した値を、OpenAPIで定義されているレスポンスの 型にあわせるとAPIの出来上がり

さいごに ほとんどの作業がOpenAPIファイルや、Prismaのスキーマ定義フ ァイルを更新にすることから始まる。 それから影響をうけるコードを修正していく。 という流れになるので、APIとDBのドキュメントが常に最新の状態 で残っている。 コード書く手間もそれなりに減らせる。 ので良かった。 自己流なので多分もっとスマートな方法あると思うけど…

ありがとうございました