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

53.2K Views

May 27, 22

#OpenAPI #Prisma #TypeScript #API開発 #個人開発

スライド概要

nomeshi74

@shin1kt

スライド一覧

またはPlayer版

埋め込む »CMSなどでJSが使えない場合

ダウンロード

ダウンロード(pdf - 1.58MB)

関連スライド

猫でも分かるUnreal Engineの学び方 - 超初心者向け編 - 2023 v1.0

ue4 ue5 ue-beginner

エピックゲームズジャパン 1.3M

Unreal Engine5 Lumenの仕組みと肝心なところ

ue5 ue-rendering ue-lumen

エピックゲームズジャパン 1.1M

SQL滅ぶべし

株式会社ホクソエム 849.4K

猫でも分かる UE5.0, 5.1 におけるアニメーションの新機能について【CEDEC+KYUSHU 2022】

ue5 cedec+kyushu ue-animation ue-optimize ue-bp ue-physics ue-sequencer

エピックゲームズジャパン 797.2K

SPAセキュリティ超入門

security php javascript

徳丸浩 790.1K

各ページのテキスト

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の書き方

10.

OpenAPIの書き方

11.

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

12.

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

13.

axiosのコードを自動生成

14.

TypeScriptの型を自動生成

15.

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

16.

[beta]

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

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

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

17.

導入前イメージ

18.

導入後イメージ

19.

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

20.

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

21.

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

22.

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

23.

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

24.

スキーマ $ prisma migrate dev

25.

テーブル users posts

26.

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

27.

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

28.

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

29.

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

30.

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

31.

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

32.

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

33.

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

34.