【Next.js】API router の API仕様書を自動生成する（TypeScript）

next-openapi-gen というライブラリを使用して、Next.jsで API 仕様書を自動生成する方法を調べたので、備忘録として記載しておきます

ライブラリを導入することで、以下の様な API 仕様書ページを生成することができます

サンプルコード

以下リポジトリに実装した内容を入れたので、ご参照ください

導入方法

1. パッケージをインストール

("devDependencies"に追加するため、--save-devを付ける）

npm install next-openapi-gen --save-dev

2. next-openapi-gen を初期化する

next.openapi.json の自動生成などの処理が行われます

npx next-openapi-gen init

APIドキュメントの生成

1. public/openapi.json の生成

以下コマンドを実行し、/public/openapi.jsonを生成することで、アプリ側が openapi.jsonを読み取り、UI上にドキュメントを自動生成してくれます

npx next-openapi-gen generate

API ドキュメントの閲覧

アプリを起動した上で、http://localhost:3000/api-docsページにアクセスすることで、API ドキュメントを閲覧することができます

API のドキュメント化

ライブラリの仕様に沿った記載方法でコメントを記載することで、生成されるAPIドキュメントに、コード内のコメント内容を反映することができます
基本的な形式としては、以下のアノテーションに対して type（以下例だとUserResponse）を定義することで JSON を仕様書に反映することができます

戻り値（response）

省略することもできますが、「ステータス:type」で定義することで、戻りステータスを定義することができます

/api/users/route.ts

type UserResponse = {
  id: number; // ユーザーID
  name: string; // ユーザー名
}

/**
 * ユーザー一覧取得
 * @description API に対しての補足説明
 * @response 200:UserResponse
 * @responseDescription 戻り値に対しての補足説明
 */
export const GET = () => {

リクエストパラメータ（params）

/api/users/route.ts

type GetRequestData = {
  id: number; // ユーザーID
}

/**
 * ユーザー一覧取得
 * @params GetRequestData
 */
export const GET = (request: NextRequest) => {
  const searchParams = request.nextUrl.searchParams;
  const id = searchParams.get("id");

パスパラメータ（pathParams）

/api/users/[id]/route.ts

type PathParamData = {
  id: number; // ユーザーID
}

/**
 * ユーザー一覧取得
 * @pathParams PathParamData
 */
export const GET = (request: NextRequest) => {
  const searchParams = request.nextUrl.searchParams;
  const address = searchParams.get("id");

リクエストボディ（body）

/api/users/route.ts

type RequestBody = {
  name: string; // ユーザー名
  email: string; // メールアドレス
}

/**
 * ユーザー一覧取得
 * @body RequestBody
 */
export const POST = async (request: NextRequest) => {
  const json: NextRequest = await request.json();

戻りステータスの追加（add）

/api/users/route.ts

/**
 * ユーザー一覧取得
 * @response 200
 * @add 404:Empty
 */
export const POST = async (request: NextRequest) => {
  const json: NextRequest = await request.json();

出力設定の変更（next.openapi.json）

openapi.jsonの出力に関わるコンフィグを変更できます

schemaType

zodか、typescriptのいずれかの値を設定します
javascript で実装されている場合はzodを使用する必要がありますが、TypeScriptで実装されている場合はtypescriptを設定することで、zod による定義が不要になります

apiDir

/apiフォルダーのパスを設定します
ここのパスが実際の環境と違っていると、openapi.jsonに実装済みのAPIが出力されないため、注意が必要です

参照

以下が公式の npm と Github のドキュメントページです