MENU
  1. ホーム
  2. TypeScript
  3. 自分のプロジェクトのAPI・DB設計を理解するためのツール＆手法まとめ（Swagger / OpenAPI / Redoc / Redocly CLI）

自分のプロジェクトのAPI・DB設計を理解するためのツール＆手法まとめ（Swagger / OpenAPI / Redoc / Redocly CLI）

TypeScript

最近はCopilotやChatGPTなどのAIツールを使えば、バックエンドAPIが数分で動くコードとして生成されます。でも、「動いてはいるけど中身がわからない」状態は危険です。バグが出たとき、機能追加したいとき、自分のコードなのに手が出せなくなります。

この記事では、自分のプロジェクトのAPI仕様やDB設計を「見える化」して理解するためのツールと手法を、実務で使える形で整理します。

目次

「動くものを作る」と「理解して改修できる」は別のスキルです

AIでコードを生成するワークフローが当たり前になった今、「とりあえず動く」コードは簡単に手に入ります。しかし以下のような場面では、コードの中身を理解していないと詰まります。

  • バグの原因調査 — エラーログを読んでも、どのルートのどの処理が該当するか分からない
  • 機能追加・仕様変更 — テーブルのリレーションが把握できず、どこにカラムを足すべきか判断できない
  • コードレビューや質問への対応 — 「このAPIは何をしているの？」と聞かれたときに答えられない

後者を身につけるために、まずは可視化から始めましょう。

API仕様を可視化する、Swagger（OpenAPI）

OpenAPIとSwaggerの関係

この2つは混同されがちですが、役割が違います。

  • OpenAPI Specification（OAS） — REST APIの構造をYAMLやJSONで記述するための仕様（フォーマット）
  • Swagger — その仕様に基づいて動くツール群の総称

もともとSwaggerという名前で仕様もツールも一体だったのですが、2016年にAPI仕様の部分が「OpenAPI Specification」として標準化され、Swaggerはツール群のブランド名として残りました。

つまり、「OpenAPIのルールに従って書いた定義ファイルを、Swaggerのツールで可視化・テストする」という関係です。

（導入事例）Express + swagger-jsdoc + swagger-ui-express の仕組み

Swagger UIを直接YAMLファイルから使うのではなく、コード中のコメント（JSDoc形式）からAPI定義を自動生成するアプローチが一般的です。

手順

  1. パッケージインストール
npm install swagger-jsdoc swagger-ui-express
  1. swagger.tsを作成

ここで「APIのタイトル」「バージョン」「スキーマ定義」「どのファイルからコメントを読み取るか（apis）」を設定しています。

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)
  1. ルートファイルに @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の仕様書になるので、コメントを読めばそのエンドポイントが「何を受け取って」「何を返すか」が分かります。

  1. Swagger UIをマウントする

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ドキュメントがブラウザで見られるようになります。

Swagger UIで確認できること

Swagger UIを開くと、各エンドポイントについて以下の情報がビジュアルで確認できます。

  • パスとHTTPメソッド（POST /auth/login）
  • リクエストボディのJSON構造
  • レスポンスのステータスコード別のデータ構造
  • 認証の要否（鍵アイコンの有無）
  • Try it out ボタンで、ブラウザから直接APIを叩いてテストもできる

自分のプロジェクトにSwaggerが入っているなら、まずSwagger UIを開いて全エンドポイントを眺めることが「API理解」の最も手軽な第一歩です。

その他フレームワークでは

主要なもの

フレームワーク言語Swagger/OpenAPI対応ライブラリ
NestJSTypeScript@nestjs/swagger（デコレータから自動生成）
FastAPIPython標準で組み込み（追加ライブラリ不要）
Django REST FrameworkPythondrf-spectacular, drf-yasg
FlaskPythonflask-restx, flasgger
Spring BootJavaspringdoc-openapi（旧springfox）
Ruby on RailsRubyrswag
LaravelPHPl5-swagger, scramble
ASP.NET CoreC#.NET 9以降は標準組み込み。それ以前はSwashbuckle
Gin / EchoGoswag（コメントから自動生成）

サポートされていないフレームワークもプラグイン経由で対応できます

例）Serverless Framework

主なやり方は2つあります。

  • serverless.ymlからOpenAPI定義を生成するプラグイン

serverless-openapi-documenterというプラグインがあり、serverless.ymlのカスタムセクションとhttp/httpApiイベントにドキュメント情報を書くことで、OpenAPI 3.0のJSON/YAMLファイルを生成できます

  • swagger-jsdocを併用する

Lambda関数のコード内に@openapiコメントを書き、swagger-jsdocで解析するアプローチもあります。

もうひとつの選択肢、Redoc / Redocly CLI

Swagger UIとの違い

Swagger UIとRedocはどちらもOpenAPI定義ファイルからAPIドキュメントを生成しますが、設計思想が異なります。

Swagger UIはインタラクティブな開発者ツールです。「Try it out」ボタンでブラウザから直接APIを叩けるので、開発中のテストに向いています。一方Redocは読みやすさ重視のドキュメントを生成します。3カラムレイアウト（説明・パラメータ・レスポンス例が横並び）で、エンドポイント数が多いAPIでも一覧性が高く、外部公開用のAPI仕様書として使われることが多いです。

Redocly CLIはRedocの上位にあるCLIツールで、ドキュメント生成に加えてOpenAPI定義ファイルのlint（バリデーション）やbundle（ファイル分割・結合）もカバーします。

メリット・デメリット

Redoc / Redocly CLIのメリット

  • UIのデザインが洗練されており、カスタマイズ性も高い（ブランディングに合わせた色・ロゴの変更など）
  • redocly lint でOpenAPI定義のルール違反を検出できる。CI/CDに組み込めば、仕様の品質を自動チェックできる
  • redocly bundle で $ref で分割した複数ファイルを1つにまとめられる。大規模APIで定義ファイルを分割管理しているプロジェクトに有用
  • OpenAPI 3.2、3.1、3.0、Swagger 2.0に対応しており、仕様バージョンの幅が広い
  • HTMLファイルとして静的ビルドできるので、サーバーなしでもドキュメントを配布・共有できる

デメリット

  • Redoc単体にはSwagger UIのような「Try it out」機能がない（ブラウザからAPIを直接叩けない）。開発中のテスト用途にはSwagger UIのほうが便利
  • 高度なカスタマイズや複数API管理などはRedoclyの有料プラン（月額$69〜）が必要
  • Swagger UIと比べるとコミュニティの規模が小さく、トラブル時に参考にできる日本語情報が少ない

使い分けの目安

  • 開発中にAPIの動作確認もしたい → Swagger UI
  • 見やすい仕様書を外部に公開したい → Redoc
  • OpenAPI定義の品質管理やファイル分割管理もしたい → Redocly CLI

両方を併用するプロジェクトも珍しくありません。開発環境ではSwagger UIを使い、公開用ドキュメントはRedocで生成する、という使い分けです。

導入例（静的HTMLの生成）

bash

# Redocly CLIのインストール
npm install -g @redocly/cli

# OpenAPI定義ファイルのバリデーション
redocly lint openapi.yaml

# 静的HTMLドキュメントの生成
redocly build-docs openapi.yaml -o api-docs.html

生成された api-docs.html をブラウザで開くだけで、3カラムレイアウトのAPIドキュメントが見られます。Express等にマウントする必要がないので、既存のプロジェクト構成を変えずに導入できます。

Expressに組み込む場合

Swagger UIのようにExpressのルートにマウントしたい場合は、Redocのexpressミドルウェアも使えます。

typescript

import redoc from 'redoc-express'

app.get('/api-docs/openapi.json', (req, res) => {
  res.sendFile('openapi.json', { root: '.' })
})

app.get(
  '/api-docs',
  redoc({
    title: 'My API Docs',
    specUrl: '/api-docs/openapi.json',
  })
)

その他API開発ツール

https://chromewebstore.google.com/detail/requestly-supercharge-you/mdnleldcmiljblolnjhpnblkcekpdkpa?hl=ja

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: 'カラム名' })外部キーのカラム名を明示する

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との連携もできます。

TypeScript

関連記事

目次