📄
Swagger✕NestJSで簡単なAPIドキュメントをつくる記事
はじめに
今回の記事では、SwaggerとNestJSを使った簡単なSwaggerドキュメントの雛形を作成する。
対象とする読者
- TypeScriptで簡単なAPIサーバを立ち上げたい人
- 現在Swagger、あるいはNestJSを学んでいる人
- タイトルでなんとなく気になった人
手順
@nestjs/swaggerは、NestJSアプリケーションのAPIドキュメントを自動生成するためのライブラリです。Swagger UIを使用して、APIのエンドポイントやリクエスト/レスポンスの形式を視覚的に表示することができます。
以下は、NestJSで@nestjs/swaggerを使用して簡単なAPIドキュメントを出力する手順とサンプルコードです：
(1) 必要なパッケージのインストール
以下のコマンドを入力する。
npm install @nestjs/cli @nestjs/swagger
npx nest new sample-api
(2) Swaggerの設定
main.tsファイル（またはアプリケーションのエントリーポイント）でSwaggerを設定する。
src/main.ts
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const options = new DocumentBuilder()
.setTitle('Sample API')
.setDescription('Sample API description')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(app, options);
SwaggerModule.setup('api-docs', app, document);
await app.listen(3000);
}
bootstrap();
上述のsrc/main.tsで注目するべきコードは非同期関数bootstrap()だ。
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const options = new DocumentBuilder()
.setTitle('Sample API')
.setDescription('Sample API description')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(app, options);
SwaggerModule.setup('api-docs', app, document);
await app.listen(3000);
}
上述の関数内にある定数optionsでは、NestJS上で出力するSwaggerドキュメントの情報を定義する。optionsでは、主に以下の情報を定義する。
-
.setTitle()：APIドキュメントの名前をつける -
.setDescription()：APIドキュメントの説明文をつける -
.setVersion()：APIのバージョンを定義する
そして、以下のコードを書くことでSwaggerのAPIドキュメントを生成できるのだ。
const document = SwaggerModule.createDocument(app, options); // ドキュメントの定義
SwaggerModule.setup('api-docs', app, document) // ドキュメントの起動
(3) エンドポイントの設定
エンドポイントにSwaggerのデコレータを追加して、APIの情報を記載する。
/src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { ApiOperation, ApiResponse } from '@nestjs/swagger';
@Controller('sample')
export class AppController {
// (1) HTTPリクエストの定義
@Get()
// (2) Controller上で実行することを要約する
@ApiOperation({ summary: 'Get sample data' })
// (3) 対応するHTTPステータスコードとその説明を書く
@ApiResponse({ status: 200, description: 'Success' })
getSampleData() {
return { message: 'Sample data' };
}
}
(4) APIドキュメントの確認
上記の設定を完了した後、ブラウザでhttp://localhost:3000/api-docsにアクセスすると、Swagger UIを通じてAPIドキュメントを確認できる。サーバを立ち上げる際には以下のコマンドを入力しよう。
npm run dev
ディレクトリ
本プロジェクトの最終ディレクトリを以下に示す。
/path/to/your/project/
├── src/
│ ├── app.controller.ts # エンドポイントの設定が含まれているファイル
│ ├── app.module.ts # モジュールの設定が含まれているファイル
│ ├── main.ts # アプリケーションのエントリーポイント
│ └── ... # その他のサービス、モジュール、エンティティなど
├── package.json # プロジェクトの依存関係やスクリプトが定義されているファイル
├── tsconfig.json # TypeScriptのコンパイラオプションが定義されているファイル
└── ... # その他の設定ファイルやREADMEなど
参考サイト
Discussion