最近はCopilotやChatGPTなどのAIツールを使えば、Express + TypeORM のバックエンドAPIが数分で動くコードとして生成されます。でも、「動いてはいるけど中身がわからない」状態は危険です。バグが出たとき、機能追加したいとき、自分のコードなのに手が出せなくなります。
この記事では、自分のプロジェクトのAPI仕様やDB設計を「見える化」して理解するためのツールと手法を、実務で使える形で整理します。
そもそもなぜ「理解」が必要なのか
AIでコードを生成するワークフローが当たり前になった今、「とりあえず動く」コードは簡単に手に入ります。しかし以下のような場面では、コードの中身を理解していないと詰まります。
- バグの原因調査 — エラーログを読んでも、どのルートのどの処理が該当するか分からない
- 機能追加・仕様変更 — テーブルのリレーションが把握できず、どこにカラムを足すべきか判断できない
- コードレビューや質問への対応 — 「このAPIは何をしているの？」と聞かれたときに答えられない
「動くものを作る」と「理解して改修できる」は別のスキルです。後者を身につけるために、まずは可視化から始めましょう。
1. API仕様を可視化する：Swagger（OpenAPI）
OpenAPIとSwaggerの関係
この2つは混同されがちですが、役割が違います。
- OpenAPI Specification（OAS） — REST APIの構造をYAMLやJSONで記述するための仕様（フォーマット）
- Swagger — その仕様に基づいて動くツール群の総称
もともとSwaggerという名前で仕様もツールも一体だったのですが、2016年にAPI仕様の部分が「OpenAPI Specification」として標準化され、Swaggerはツール群のブランド名として残りました。
つまり、「OpenAPIのルールに従って書いた定義ファイルを、Swaggerのツールで可視化・テストする」という関係です。
Swaggerの主要ツール3つ
| ツール | 役割 |
|---|---|
| Swagger Editor | ブラウザ上でOpenAPI定義をYAML/JSONで編集できるエディタ。リアルタイムプレビューあり |
| Swagger UI | OpenAPI定義をもとに、ブラウザで見られるインタラクティブなAPIドキュメントを生成する |
| Swagger Codegen | 定義ファイルからサーバーやクライアントのコードを自動生成する（現在はOpenAPI Generatorが主流） |
Express + swagger-jsdoc + swagger-ui-express の仕組み
Node.js/Expressのプロジェクトでは、Swagger UIを直接YAMLファイルから使うのではなく、コード中のコメント（JSDoc形式）からAPI定義を自動生成するアプローチが一般的です。ここで登場するのが以下の2つのnpmパッケージです。
swagger-jsdoc — ルートファイルに書かれた @openapi コメントを解析し、OpenAPI仕様のJSONオブジェクトを生成するライブラリです。設定ファイルでは以下のような情報を定義します。
// swagger.ts（設定ファイル）
import swaggerJsdoc from 'swagger-jsdoc'
const options: swaggerJsdoc.Options = {
definition: {
openapi: '3.0.0', // OpenAPIのバージョン
info: {
title: 'My API', // APIのタイトル
version: '1.0.0', // APIのバージョン
},
servers: [
{ url: '/api' }, // APIのベースURL
],
components: {
schemas: {
// ここにレスポンスやリクエストのデータ構造を定義
},
},
},
apis: ['./src/routes/*.ts'], // @openapi コメントを探すファイルパス
}
export const swaggerSpec = swaggerJsdoc(options)
ポイントは apis の指定です。ここに書いたパスのファイルを読み込んで、@openapi ブロックを収集します。
swagger-ui-express — 上で生成したJSONを受け取り、Express上にSwagger UIの画面をホスティングするミドルウェアです。
// index.ts や app.ts
import swaggerUi from 'swagger-ui-express'
import { swaggerSpec } from './swagger'
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))
これだけで http://localhost:3000/api-docs にアクセスすると、APIドキュメントがブラウザで見られるようになります。
ルートファイルの @openapi コメントの読み方
ルートファイル（routes/auth.ts 等）に書かれているコメントブロックが、そのままAPIドキュメントになります。基本構造を見てみましょう。
/**
* @openapi
* /auth/login: ← エンドポイントのパス
* post: ← HTTPメソッド
* tags: [Auth] ← UIでのグループ分け
* summary: ログイン ← 一行の説明
* description: メールアドレスとパスワードでログインし、JWTトークンを取得します。
* requestBody: ← リクエストボディの定義
* required: true
* content:
* application/json:
* schema:
* type: object
* required: [email, password]
* properties:
* email:
* type: string
* format: email
* password:
* type: string
* responses: ← レスポンスの定義
* 200:
* description: ログイン成功
* 401:
* description: 認証失敗
*/
router.post('/login', async (req, res) => {
// 実際のハンドラ処理
})
これはYAML形式でOpenAPIの仕様に従って書かれています。コメントの中身がそのままAPIの仕様書になるので、コメントを読めばそのエンドポイントが「何を受け取って」「何を返すか」が分かります。
Swagger UIで確認できること
Swagger UIを開くと、各エンドポイントについて以下の情報がビジュアルで確認できます。
- パスとHTTPメソッド（
POST /auth/login） - リクエストボディのJSON構造
- レスポンスのステータスコード別のデータ構造
- 認証の要否（鍵アイコンの有無）
- Try it out ボタンで、ブラウザから直接APIを叩いてテストもできる
自分のプロジェクトにSwaggerが入っているなら、まずSwagger UIを開いて全エンドポイントを眺めることが「API理解」の最も手軽な第一歩です。
2. DB設計を可視化する：ER図とTypeORMのEntity
ER図とは
ER図（Entity Relationship Diagram）は、データベースのテーブル構造とテーブル間の関係を図にしたものです。「このテーブルはどんなカラムを持っていて、どのテーブルと紐づいているか」が一目で分かります。
TypeORMのEntityからDB構造を読み解く
TypeORMを使っている場合、Entityファイルがそのままデータベースのテーブル定義です。以下のデコレータ（@で始まる記述）の意味を押さえておけば、コードからDB構造が読めるようになります。
| デコレータ | 意味 |
|---|---|
@Entity('テーブル名') | このクラスがDBのテーブルに対応する |
@PrimaryGeneratedColumn() | 自動採番の主キー（id） |
@Column({ type: '...' }) | 通常のカラム。typeでデータ型を指定 |
@CreateDateColumn() | レコード作成日時を自動設定 |
@UpdateDateColumn() | レコード更新日時を自動設定 |
@DeleteDateColumn() | 論理削除用の日時カラム（ソフトデリート） |
@ManyToOne(() => 相手) | 多対1のリレーション（このテーブルが「多」側） |
@OneToMany(() => 相手) | 1対多のリレーション（このテーブルが「1」側） |
@JoinColumn({ name: 'カラム名' }) | 外部キーのカラム名を明示する |
リレーションの読み方（実例）
たとえば「クイズアプリ」のDB設計を考えてみましょう。
QuizCategory（カテゴリ） → Quiz（クイズ問題）
カテゴリ1つに対して複数のクイズが紐づきます。これは1対多の関係です。
QuizCategory側: @OneToMany(() => Quiz, (quiz) => quiz.category)
Quiz側: @ManyToOne(() => QuizCategory, (category) => category.quizzes)
@JoinColumn({ name: 'category_id' })
この場合、quizテーブルに category_id という外部キーカラムが作られ、quiz_categoryテーブルのidを参照します。
Quiz（クイズ） → QuizChoice（選択肢）
1つのクイズに対して複数の選択肢があります。これも1対多です。
Quiz側: @OneToMany(() => QuizChoice, (choice) => choice.quiz)
QuizChoice側: @ManyToOne(() => Quiz, (quiz) => quiz.choices)
@JoinColumn({ name: 'quiz_id' })
Quiz ↔ QuizTag（多対多）
1つのクイズに複数のタグを付けられ、1つのタグが複数のクイズに使われます。TypeORMでは中間テーブル（QuizTagging）を自分で作るパターンもあります。
QuizTagging: quiz_id + quiz_tag_id の組み合わせがユニーク
このように、Entityファイルを読めばテーブル間の親子関係や中間テーブルの存在が把握できます。
ER図を自動生成するツール
手動でER図を描くのは面倒ですし、コードとの乖離が発生しがちです。自動生成ツールを使いましょう。
dbdiagram.io — ブラウザ上で使える無料ツール。SQLのDDL（CREATE TABLE文）をインポートするだけでER図が生成されます。DBMLというシンプルな記法で直接書くこともできます。
DBeaver — 無料のデータベース管理ツール。MySQLなどに直接接続して、テーブル構造からER図を自動表示できます。実際のDBに接続するので、常に最新の状態が見られるのが強みです。
Liam ERD — GitHubのスキーマファイルから直接ER図を生成できるツール。Prismaスキーマに対応しており、CLIとしてローカルでも使えます。
draw.io（diagrams.net） — 汎用の作図ツール。ER図のテンプレートがあり、手動で作りたい場合に便利。Google Driveとの連携もできます。
3. APIの基本を理解する：HTTPメソッドとREST
Swagger UIを読むにも、まずHTTPメソッドとRESTの基本を押さえておく必要があります。
HTTPメソッドの使い分け
| メソッド | 用途 | 例 |
|---|---|---|
GET | データの取得 | ユーザー一覧を取得、クイズの詳細を取得 |
POST | データの新規作成 | ユーザー登録、ファイルアップロード |
PUT | データの全体更新 | ユーザー情報をまるごと上書き |
PATCH | データの部分更新 | 名前だけ変更、パスワードだけ変更 |
DELETE | データの削除 | ユーザーの削除 |
RESTful APIのURL設計パターン
RESTでは、URLはリソース（データの種類）を表し、HTTPメソッドで操作を表現します。
GET /users → ユーザー一覧の取得
POST /users → ユーザーの新規作成
GET /users/:id → 特定ユーザーの取得
PATCH /users/:id → 特定ユーザーの部分更新
DELETE /users/:id → 特定ユーザーの削除
URLに動詞を入れないのがRESTの原則です。「/getUsers」ではなく「GET /users」とします。
認証の仕組み（JWT / OAuth）
多くのAPIでは認証が必要です。よく使われる2つの方式を簡単に説明します。
JWT（JSON Web Token） — ログイン時にサーバーがトークン（暗号化された文字列）を発行し、以降のリクエストではそのトークンを Authorization: Bearer <token> ヘッダーに付けて送ります。サーバーはトークンを検証してユーザーを特定します。
OAuth（Google ログインなど） — 外部サービス（Google、GitHub等）の認証を使う仕組みです。ユーザーがGoogleの画面で許可すると、アプリ側にユーザー情報が渡されます。自前でパスワード管理をしなくてよいのがメリットです。
Swagger UIで鍵アイコンが付いているエンドポイントは認証が必要なAPIです。security: [bearerAuth: []] と書かれていたらJWT認証、OAuthの場合はリダイレクト系のエンドポイントが定義されています。
4. 手を動かして理解する：APIテストツール
ドキュメントを読むだけでなく、実際にAPIを叩いてレスポンスを見ると理解が深まります。
Swagger UI の Try it out
前述のとおり、Swagger UIには各エンドポイントに「Try it out」ボタンがあります。パラメータを入力して「Execute」を押すと、実際のリクエストとレスポンスが表示されます。最も手軽なテスト方法です。
Postman
APIテストの定番ツール。GUIでリクエストを組み立てて送信し、レスポンスを見やすく表示してくれます。リクエストをコレクションとして保存できるので、テストケースの管理にも使えます。環境変数の切り替え（開発 / 本番）にも対応しています。
VS Code 拡張：REST Client / Thunder Client
エディタから離れずにAPIテストしたい場合に便利です。
- REST Client —
.httpファイルにリクエストを書いて、クリック一つで送信できる - Thunder Client — VS Code内でPostmanに近いGUIが使える拡張機能
cURL
ターミナルから直接HTTPリクエストを送るコマンドラインツール。スクリプトに組み込んだり、他の人にリクエスト例を共有するときに便利です。
curl -X POST http://localhost:3000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "password": "password123"}'
5. まとめ：理解のための3ステップ
自分のプロジェクトのAPI・DB設計を理解するには、以下の順序で進めるのがおすすめです。
ステップ1：Swagger UIを開いて全エンドポイントを確認する まず全体像を把握します。どんなAPIがあり、何を受け取って何を返すのかをざっと見ます。
ステップ2：EntityファイルからDB構造とリレーションを読み解く テーブル間の関係を理解します。余裕があればER図ツールで可視化しましょう。
ステップ3：実際にAPIを叩いてリクエスト・レスポンスを確認する Swagger UIのTry it outやPostmanで、実データの流れを体感します。
AIがコードを書いてくれる時代だからこそ、「理解してから改修する」習慣を持つことが、エンジニアとしての成長に直結します。まずはSwagger UIを開くところから始めてみてください。
