Blue Archive API

ブルーアーカイブの生徒データAPI & フロントエンドアプリケーション

🌐 Live Demo | 📖 API ドキュメント | 📋 利用規約

---

特徴

• 高機能検索: 学校・レア度・武器・攻撃タイプ・防御タイプでフィルタリング
• レスポンシブデザイン: モバイル・タブレット・デスクトップ対応
• パフォーマンス最適化: キャッシュ機能とレート制限
• セキュリティ: CORS・ヘルメット・レートリミッター実装
• OGP 対応: SNS シェア向けに Open Graph / Twitter カードを自動生成
• 詳細なAPIドキュメント: 実装例とトラブルシューティング付き

🚀 クイックスタート

前提条件

• Node.js 18+
• Bun

セットアップ

# リポジトリをクローン
git clone https://github.com/ibuki-hum4/BlueArchiveAPI.git
cd BlueArchiveAPI

# フロントエンドディレクトリに移動
cd frontend

# 依存関係をインストール
bun install

# 開発サーバーを起動
bun run dev

アプリケーションは http://localhost:3000 で起動します。

Go API版を起動する

既存の Next.js API を変更せず、互換APIを go-api に追加しています。

# Go API ディレクトリに移動
cd go-api

# サーバー起動（既定: 8080）
go run .

OGP レンダラー (Bun + TSX) を起動する

Go API の /api/og は、og-renderer マイクロサービスの POST /render を呼び出して PNG を返します。

cd og-renderer
bun install
bun run start

既定では http://localhost:8787/render を使用します。別URLを使う場合は、Go API 起動時に以下を指定してください。

OGP_RENDERER_URL=http://localhost:8787/render go run ./go-api

Go API + OGP レンダラーを Docker で起動する

# 1) OGP renderer イメージをビルド
docker build -t kemar1/bluearchive-og-renderer:0.1.0 ./og-renderer

# 2) Go API イメージをビルド
docker build -t kemar1/bluearchive-api-go:0.1.0 ./go-api

# 3) 同一ネットワークを作成
docker network create bluearchive-net

# 4) OGP renderer を起動（フォントをマウント）
docker run -d --name bluearchive-og-renderer --network bluearchive-net -p 8787:8787 `
	-e OGP_FONT_REGULAR_PATH=/app/fonts/BIZUDPGothic-Regular.ttf `
	-e OGP_FONT_BOLD_PATH=/app/fonts/BIZUDPGothic-Bold.ttf `
	-v "${PWD}/og-renderer/fonts:/app/fonts:ro" `
	kemar1/bluearchive-og-renderer:0.1.0

# 5) Go API を起動（renderer URL を内部DNSへ向ける）
docker run -d --name bluearchive-go-api --network bluearchive-net -p 8080:8080 `
	-e OGP_RENDERER_URL=http://bluearchive-og-renderer:8787/render `
	-e STUDENTS_DATA_PATH=/app/data/students.json `
	-v "${PWD}/data:/app/data:ro" `
	kemar1/bluearchive-api-go:0.1.0

動作確認:

curl "http://localhost:8080/api/og?id=10000" --output ogp.png

Go API は http://localhost:8080 で起動し、次のエンドポイントを提供します。

• GET /api
• GET /api/health
• GET /api/students
• GET /api/students/:id
• POST /api/students

必要に応じて、フロントエンドの NEXT_PUBLIC_API_BASE_URL を http://localhost:8080/api に設定して接続先を切り替えられます。

📂 プロジェクト構造

BlueArchiveAPI/
├── data/                    # 生徒データ (JSON)
│   └── students.json
├── frontend/               # Next.js アプリケーション
│   ├── src/
│   │   ├── app/           # App Router
│   │   │   ├── api/       # API Routes
│   │   │   ├── [id]/      # 動的ルート (生徒詳細)
│   │   │   ├── api-docs/  # API ドキュメント
│   │   │   └── terms/     # 利用規約
│   │   ├── components/    # React コンポーネント
│   │   ├── lib/          # ユーティリティ
│   │   ├── hooks/        # カスタムフック
│   │   └── types/        # TypeScript 型定義
│   ├── public/           # 静的ファイル
│   └── tailwind.config.ts
└── README.md

🌐 API エンドポイント

メソッド	エンドポイント	説明
GET	/api/students	全生徒データを取得
GET	/api/students/[id]	指定IDの生徒データを取得
POST	/api/students	新しい生徒データを追加 (要認証)

使用例

// 全生徒データを取得
const response = await fetch('/api/students');
const data = await response.json();

// 学校で絞り込み
const students = await fetch('/api/students?school=ゲヘナ学園');

// 特定の生徒を取得
const student = await fetch('/api/students/B5F50C9O');

詳細な使用方法は API ドキュメント をご確認ください。

🛠️ 開発

利用可能なスクリプト

# 開発サーバー起動
bun run dev

# プロダクションビルド
bun run build

# プロダクションサーバー起動
bun run start

# リンター実行
bun run lint

環境変数

デフォルトでは .env ファイルがなくても動作します。Next.js 内部の API を利用するため、特別な設定は不要です。

外部の API や別ホストを利用したい場合のみ、任意で以下のような環境変数を設定してください。

# .env.local（任意）
NEXT_PUBLIC_API_BASE_URL=https://example.com/api

🚢 デプロイ

Vercel (推奨)

1. GitHub リポジトリを Vercel に接続
2. frontend ディレクトリを Root Directory に設定
3. 必要に応じて環境変数を設定
4. デプロイ実行

Docker Hub へビルド & プッシュ

# Docker Hub にログイン
docker login

# ルートディレクトリでビルド
docker build -t kemar1/bluearchive-api:0.1.0 .

# 動作確認 (任意)
docker run --rm -p 3000:3000 kemar1/bluearchive-api:0.1.0

# タグを最新に付け替え（任意）
docker tag kemar1/bluearchive-api:0.1.0 kemar1/bluearchive-api:latest

# プッシュ
docker push kemar1/bluearchive-api:0.1.0
docker push kemar1/bluearchive-api:latest

kemar1/ の部分はご自身の Docker Hub ユーザー名に置き換えてください。

Kubernetes にデプロイする場合

• manifests/deployment.yaml の image は docker.io/kemar1/bluearchive-api:0.1.0 を指しています。Docker Hub にプッシュしたタグに合わせて docker.io/<your-username>/bluearchive-api:<tag> に更新してください。
• 新しいバージョンを展開する際は、kubectl apply -f manifests/ を実行する前にタグを更新し、kubectl rollout restart deployment/bluearchive-api で再起動すると確実です。
• manifests/ingress.yaml の host は本番ドメイン bluearchive-api.skyia.jp を設定しています。別ドメインで公開する場合は、DNS とあわせてこの値を変更してください。
• manifests/pvc.yaml はクラスタのデフォルト StorageClass を利用するようになりました。ReadWriteMany が必要な場合は、ご自身の環境で RWX 対応の StorageClass を作成し、storageClassName と accessModes を書き換えてください（その場合、Deployment の replicas を 2 以上にしても問題ありません）。
• シングルノード構成やデフォルト StorageClass（たとえば standard）を使う場合はそのまま適用できますが、Pod が複数ノードにスケジュールされると ReadWriteOnce ボリュームは共有できない点にご注意ください。

🤝 貢献

1. このリポジトリをフォーク
2. フィーチャーブランチを作成 (git checkout -b feature/amazing-feature)
3. 変更をコミット (git commit -m 'Add amazing feature')
4. ブランチにプッシュ (git push origin feature/amazing-feature)
5. プルリクエストを作成

📄 ライセンス

本プロジェクトで使用されているデータおよびアセットは、ブルーアーカイブの著作権者に帰属します。 本プロジェクトは非営利目的での使用を想定しており、商用利用は禁止されています。 詳細は 利用規約 をご覧ください。

コード部分の著作権は ibuki-hum4 に帰属します。 コードの使用・改変・再配布は非営利目的に限り許可されます。 商用利用や再配布は禁止です。 コントリビューション（Pull Request、Issue など）は歓迎します。

🙏 謝辞

• ブルーアーカイブ - ゲームデータの提供
• Next.js - フレームワーク
• Tailwind CSS - UI フレームワーク