🎯 目的

NestJSでREST APIを定義
OpenAPI (Swagger) 仕様を自動生成
Next.jsでOpenAPI仕様から型とAPIクライアントを自動生成
フロントとバックで安全＆効率的な連携を実現

🧱 ステップ全体の流れ

[NestJS] APIを作る（Swagger導入）
[NestJS] Swagger UIで仕様を確認
[Next.js] OpenAPIから型/クライアントを自動生成（openapi-typescript など）
[Next.js] 安全にAPIを呼び出す

🧪 ステップ①：NestJSでAPI作成＆Swagger導入

🔧 インストール

npm install @nestjs/swagger swagger-ui-express

📝 コントローラ定義（例）

// user.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';

@Controller('users')
@ApiTags('Users')
export class UserController {
  @Get(':id')
  @ApiOperation({ summary: 'Get user by ID' })
  @ApiResponse({ status: 200, description: 'User found.' })
  getUser(@Param('id') id: string) {
    return { id, name: 'John Doe' };
  }
}

🧰 Swaggerの設定（main.ts）

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('User API documentation')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}

🌐 実行して確認

ブラウザで http://localhost:3000/api にアクセスすると、
Swagger UI でAPIドキュメントが見れます（＝OpenAPIのビジュアル版）

📦 ステップ②：OpenAPI仕様をJSONとしてエクスポート

import * as fs from 'fs';

const document = SwaggerModule.createDocument(app, config);
fs.writeFileSync('./openapi.json', JSON.stringify(document, null, 2));

このファイル（openapi.json）を Next.js 側にコピーして使います。

💡 ステップ③：Next.jsで型とAPIクライアントを自動生成

方法①：型だけ生成する（`openapi-typescript`）

🔧 インストール

npm install -D openapi-typescript

🔁 実行

npx openapi-typescript ./openapi.json -o types/api.d.ts

✅ 使用例（Next.js）

import type { paths } from './types/api';

type GetUserResponse = paths['/users/{id}']['get']['responses']['200']['content']['application/json'];

const res = await fetch('/users/123');
const user: GetUserResponse = await res.json();

console.log(user.name); // 型補完される！

方法②：型 + APIクライアントも自動生成（例：`orval`）

🔧 インストール

npm install -D orval

📄 orval.config.ts

export default {
  api: {
    input: './openapi.json',
    output: {
      mode: 'split',
      target: './api/',
      schemas: './api/schemas',
    },
  },
};

🔁 実行

npx orval

✅ 使用例

import { getUser } from './api/users';

const { data } = await getUser({ id: '123' });
console.log(data.name); // 型付きで安全

✅ OpenAPI導入のメリットまとめ

項目	メリット
🔧 フロントとバックの型が一致	自動生成されるのでズレなし
📖 APIドキュメント自動化	Swagger UIで可視化
🤝 チーム連携	仕様が明文化されて共有しやすい
🔄 モックやテストも自動化可	Prism, Mockoon などで活用可能

🎓 まとめ

ステップ	内容
1	NestJSでAPIとSwagger UIを構築
2	OpenAPI仕様（JSON）を出力
3	Next.jsで型やクライアントを自動生成
4	フロントから安全にAPIを叩けるようになる

🧰 もしNext.jsとNestJSが同じリポジトリなら？

OpenAPIでの連携はもちろん便利
Turborepoなどで共通型ファイル（DTO）を共有する構成でもOK
でも外部公開APIやフロント分離型構成なら OpenAPIはベストチョイス

🙋 もっと知りたい方へ

✅ openapi-typescript-codegen を使ってAxiosクライアントを生成する方法
✅ Prism や Stoplight でOpenAPIのモックサーバーを立てる方法
✅ OpenAPIとZodやTypeBoxを併用する構成

📘 OpenAPI（Swagger）仕様の `openapi.json` を NestJS で生成する方法

🔍 目的：何のために生成するの？

openapi.json は、「このAPIは何を受け取り、何を返すのか」というAPIの設計図です。これがあると：

Swagger UI や Postman でドキュメント化できる
Next.js などのフロントで、型やAPIクライアントを自動生成できる
外部開発者とAPI仕様を共有できる

つまり「コードからAPIの仕様を機械的に取り出せる」ようになります。

✅ ステップ①：必要なパッケージをインストール

npm install @nestjs/swagger swagger-ui-express

これで Swagger（OpenAPI）を扱う準備はOK。

✅ ステップ②：Swaggerを `main.ts` に組み込む

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API docs powered by Swagger')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // Swagger UI 表示（任意）
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

この時点で http://localhost:3000/api にアクセスすれば、Swagger UI が見られます。

✅ ステップ③：`openapi.json` をファイルとして保存する

✏️ コード追加（`main.ts`）

import * as fs from 'fs'; // Node.js のファイル操作用

const document = SwaggerModule.createDocument(app, config);

// ファイル出力
fs.writeFileSync('./openapi.json', JSON.stringify(document, null, 2));

🏁 実行すると：

プロジェクトルートに openapi.json というファイルが生成されます。

📦 出力された `openapi.json` はこんな内容

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "description": "API docs powered by Swagger",
    "version": "1.0"
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "summary": "Get user by ID",
        "parameters": [ ... ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" }
        }
      }
    }
  }
}

これはまさに「APIの仕様書」。この内容を使って型生成やクライアント生成ができます。

💡 よくある注意点

注意点	内容
`@ApiTags` や `@ApiResponse` を書かないと中身が空になる	Swagger用のデコレータが必要
自動出力したいなら CLI やスクリプト化もできる	`npm run generate:openapi` など
DTO にも `@ApiProperty()` を書こう	型情報が詳細に反映される

✅ 最小限のセットアップ例まとめ

// user.dto.ts
import { ApiProperty } from '@nestjs/swagger';

export class UserDto {
  @ApiProperty()
  id: string;

  @ApiProperty()
  name: string;
}

// user.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import { ApiTags, ApiResponse } from '@nestjs/swagger';
import { UserDto } from './user.dto';

@Controller('users')
@ApiTags('Users')
export class UserController {
  @Get(':id')
  @ApiResponse({ status: 200, type: UserDto })
  getUser(@Param('id') id: string): UserDto {
    return { id, name: 'Taro' };
  }
}

🔚 まとめ：NestJSで openapi.json を生成するには？

ステップ	内容
① パッケージ導入	`@nestjs/swagger` + `swagger-ui-express`
② `main.ts` にSwagger設定を書く	`DocumentBuilder + createDocument`
③ `fs.writeFileSync` で JSON 出力	任意の場所に `openapi.json` 保存
④ DTO や Controller に Swagger用デコレータを記述	`@ApiProperty()`, `@ApiResponse()` など