Notionで開発ドキュメント作ってみた

こんにちはkobo_staです。
普段はエンジニアやってます。
個人で作ってきたNotionのテンプレートを公開したいと思います。

前々から仕様書を書いていて不便だなと思っていたことがあり、Notionで実現できました。
一つ変えたらあちこちに修正が入るみたいなことってないですか？
影響がある項目が探しにくいとかないですか？
今回はそんなことをNotionで解決したいと思います。

テーブル定義

まずはテーブル定義です。テーブル一覧から見てみます。

テーブル一覧

これは特になんてことないです。
では項目です。

テーブル項目一覧

こちらも特に言うことはないですが、こちらのデータベースをテーブル一覧のページの中身に追加しています。

ユーザテーブルの詳細

こちらはテンプレート機能を使って最初からこのデータベースのリンクが入るようにしてます。
全体で見る場合とテーブル単体で見る場合それぞれ参照できるようになってます。

API

APIのドキュメントも作りました。
ますはAPI一覧

API一覧

認証部分はユーザ認証の有無を設定する感じです。

ビューでCRUDを各々で調査できる様にしています。
テーブルごとにグループ分けしていて、他のCRUDも一緒に参照するようにしてます。
これでCRUDという別の資料を作成しなくても良いし、調査も早くなります。

CRUD図まがい

続いてAPIのリクエストとレスポンスをそれぞれ見ていきます。

APIリクエスト

APIレスポンス

リクエストもレスポンスもどのテーブルのカラムに紐づくか記載しています。
カラムがリレーションでテーブルがロールアップです。（同じ項目名だと検索しにくいのでNotionさん改善求ム）
ここに紐づけていることで、参照するカラム名が変わっても自動で変わってくれます。
あと、リクエストのバリデーションはclass-validatorを使っているので、そちらを記載しています。
また、テーブルカラムの桁数もロールアップする様にしています。
文字列長のバリーデーションを基本テーブルと合わせると思うので、レビュー用含めて持ってきてます。（オプションはclass-validationのパラメータに使ってます。）

こちらのAPIのリクエスト・レスポンスもAPI一覧の詳細から見れるようにしています。

API一覧の詳細

この詳細で記載することによって、この親テーブルを毎回指定しなくて良いです。
そして、どのテーブル、どの項目に影響があるか調べたい場合は一覧から、各種APIの中身を確認したい場合はAPI一覧の詳細から参照できる様になっています。

最後に

今回はテーブルとAPIだけをお見せしましたが、実際は画面も同じように作っています。
画面は結構趣味が分かれそうだったので今回は載せませんでしたが、APIと同様にどの画面でどのAPIを使っているかも作ることができます。
また、コード定義なども同じ様に作っていて、テーブルの項目やAPIのリクエストに紐づけておくのも良いです。

テンプレートは有料版にて公開したいと思います。