NestJSを用いたWebAPIサーバーの開発と、仕様書作成/APIテストの効率化

2023-01-20

NestJSを用いたWebAPIサーバーの開発と、仕様書作成/APIテストの効率化

記事をシェアする

[！] この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

私たちのチームでは、新しく作成するREST APIサーバーの開発にNestJS、API仕様書のフォーマットにOpenAPI(Swagger)を採用しました。NestJSでは、組み込みのモジュールを利用することにより、OpenAPI仕様書を容易に作成することが可能です。
また、APIテストフレームワークにDreddを用いることで、実装がOpenAPI仕様書通りに動いているかどうかを自動で確認することができます。この記事では、NestJSとDreddに関しての説明や利点、またサンプルコードを用いて実際にAPIサーバー構築・OpenAPI仕様書作成・APIテストまでの一連の流れを紹介していきます。

記事の全体図

この記事の対象者

Node.js, OpenAPI, JavaScriptの基礎を理解している方
現在API仕様書を手動で記述している方
APIテストを自動で簡単にしてみたいと考えている方

この記事でやること

NestJSの使い方を理解し、実際にサーバーを構築
SwaggerでAPI仕様書を作成
Dreddによる自動APIテストの実行・試験結果に基づく修正

この記事でやらないこと

OpenAPI(Swagger)に関する解説は省略しています。OpenAPIに関する詳細な内容は、過去の記事で紹介していますので、こちらもあわせてご参照ください。

『OpenAPI Specificationの紹介』

用語解説

NestJS

NestJSとは、Node.jsを利用してサーバーサイドアプリケーションを構築するためのフレームワークです。
NestJSの特徴として以下が挙げられます。

TypeScriptで記述されたフレームワークなのでTypeScriptとの親和性が高い
デフォルトでNode.jsのフレームワークの一つであるExpressをコアとして動作しているため、Expressの要領で開発することが可能である
AngularライクなのでAngularを知っていればNestJSでの開発を行う際の学習コストがかかりづらくなる
今回紹介するOpenAPI仕様書作成のためのモジュールなど、組み込みの便利なモジュールがあり、かつそれらの利用が容易である

NestJSを用いることで、APIサーバーの開発に加え、仕様書の作成およびメンテナンスを効率的に行うことができます。

Dredd

Dreddは、バックエンドの実装に対してAPI仕様書通りに実装が行われているか確認できるAPIテストフレームワークです。
対応している言語は、Node.js(JavaScript)をはじめ、PythonやRubyなどがあり、言語に依存することなく使用することが可能です。
今回紹介するDreddを用いたAPIテストでは、実際にAPI仕様書を引数として渡して容易に試験することが可能となっています。

NestJSを用いてOpenAPI仕様書を自動生成する

ここからは、実際にサンプルコードを用いて簡易的なメンバー管理アプリのAPIサーバーを作成し、OpenAPI仕様書を生成したいと思います。なお、APIサーバー・API仕様書を作成するにあたり、パッケージ管理ツールであるnpm(Node Package Manager)を使用するため、事前にNode.jsをインストールする必要があります。

APIサーバー作成

まず初めに@nestjs/cliをインストールします。こちらをインストールすることで、NestJSのコマンドが入力できるようになります。

1
$ npm i -g @nestjs/cli

次に、プロジェクトを作成します。今回はプロジェクト名をmemberManageにします。

1
$ nest new memberManage

上記のコマンドをターミナル上で入力すると、以下のディレクトリが自動作成されます。今回はメンバー管理用のモジュールを別途作成するためappファイルは使用しませんが、NestJSアプリの基本の部分となります。

member-manage/src
      ├ app.controller.spec.ts
      ├ app.controller.ts
      ├ app.module.ts
      ├ app.service.ts
      └ main.ts

それぞれが持つ役割については以下になります。

ファイル名	役割
app.controller.spec.ts	app.controller.ts用のテストファイル
app.controller.ts	APIのURLに対応するServiceを呼び出す
app.module.ts	アプリ本体となり、様々なモジュールを紐づけする
app.service.ts	ビジネスロジックを記載する
main.ts	アプリを起動させるためのエントリーポイント

NestJSの仕組み

次に、CLIのCRUDジェネレーターを使い、membersのCRUDコントローラーを作成します。CRUDとは、システムに必要とされる基本の機能の「Create(作成)」・「Read(読み取り)」・「Update(更新)」・「Delete(削除)」のそれぞれの頭文字から取った用語です。今回のメンバー管理アプリに置き換えると、メンバー登録・全体(一部)参照・メンバー更新・メンバー削除の機能の枠組みがCRUDジェネレーターによって生成されます。

1
$ cd ./member-manage/
2
$ nest generate resource members

上記のコマンドをターミナル上で入力すると、./src/members下に以下のディレクトリが自動生成されます。

member-manage/src/members
      ├ dto/
      │   ├ create-member.dto.ts
      │   └ update-member.dto.ts
      ├ entities/
      │   └ member.entity.ts
      ├ members.controller.spec.ts
      ├ members.controller.ts
      ├ members.module.ts
      ├ members.service.spec.ts
      └ members.service.ts

こちらも図で解説します。先ほどの仕組みとほぼ変わりませんが、member.entity.ts, create-member.dto.ts, update-member.dto.tsが増えたことにより、データの表示・登録・更新のそれぞれでどのようなデータを扱うのかを細かく指定することができます。

コマンドによって生成される各ファイルのフロー

今回のアプリケーションでメインとなるmembers.module.ts, members.controller.ts, members.service.tsのコードを以下に添付しました。こちらのコードは、先ほどのnest generate resource membersコマンドを入力して自動生成されたコードになります。(コメントは私が追記しています)

./src/members/members.service.ts

ソースコードを開く／閉じる

1
/*
2
* インポート部分
3
* 追加することにより、モジュールを組み込んだり、
4
* 他で書かれたプログラムを繋ぎ合わせたりすることができる
5
*/
6
import { Injectable } from '@nestjs/common';
7
import { CreateMemberDto } from './dto/create-member.dto';
8
import { UpdateMemberDto } from './dto/update-member.dto';
9

10
@Injectable()
11
export class MembersService {
12

13
  // メンバー登録
14
  create(createMemberDto: CreateMemberDto) {
15
    return 'This action adds a new member';
16
  }
17

18
  // 全体参照
19
  findAll() {
20
    return `This action returns all members`;
21
  }
22

23
  // 一部参照
24
  findOne(id: number) {
25
    return `This action returns a #${id} member`;
26
  }
27

28
  // メンバー更新
29
  update(id: number, updateMemberDto: UpdateMemberDto) {
30
    return `This action updates a #${id} member`;
31
  }
32

33
  // メンバー削除
34
  remove(id: number) {
35
    return `This action removes a #${id} member`;
36
  }
37
}

./src/members/members.controller.ts

ソースコードを開く／閉じる

1
import {
2
  Controller,
3
  Get,
4
  Post,
5
  Body,
6
  Patch,
7
  Param,
8
  Delete,
9
} from '@nestjs/common';
10
import { MembersService } from './members.service';
11
import { CreateMemberDto } from './dto/create-member.dto';
12
import { UpdateMemberDto } from './dto/update-member.dto';
13

14
@Controller('members')
15
export class MembersController {
16
  constructor(private readonly membersService: MembersService) {}
17

18
  // Post(送信)のリクエストが送られた時の処理
19
  @Post()
20
  create(@Body() createMemberDto: CreateMemberDto) {
21
    return this.membersService.create(createMemberDto);
22
  }
23

24
  // Get(全体参照)のリクエストが送られた時の処理
25
  @Get()
26
  findAll() {
27
    return this.membersService.findAll();
28
  }
29

30
  // Get(一部参照)のリクエストが送られた時の処理
31
  @Get(':id')
32
  findOne(@Param('id') id: string) {
33
    return this.membersService.findOne(+id);
34
  }
35

36
  // Patch(更新)のリクエストが送られた時の処理
37
  @Patch(':id')
38
  update(@Param('id') id: string, @Body() updateMemberDto: UpdateMemberDto) {
39
    return this.membersService.update(+id, updateMemberDto);
40
  }
41

42
  // Delete(削除)のリクエストが送られた時の処理
43
  @Delete(':id')
44
  remove(@Param('id') id: string) {
45
    return this.membersService.remove(+id);
46
  }
47
}

./src/members/members.module.ts

ソースコードを開く／閉じる

1
import { Module } from '@nestjs/common';
2
import { MembersService } from './members.service';
3
import { MembersController } from './members.controller';
4

5
@Module({
6
  // controller指定
7
  controllers: [MembersController],
8
  // service相当の指定
9
  providers: [MembersService],
10
})
11
export class MembersModule {}

実際にAPIが動作しているか確認するために、試しに単体取得(GET)のAPIを動かしてみたいと思います。
まず、サーバーを起動させます。

1
$ npm start

起動が確認できたら、今回はID番号が1番のメンバーの情報を表示させたいので、ブラウザ上でhttp://localhost:3000/members/1と入力します。
そうすると、members.service.tsのfindOne()の内容がきちんとレスポンスされました。

単体取得(GET)API

API仕様書作成

必要なAPIサーバーが構築されたので、ここからAPI仕様書を作成していきます。
始めに@nestjs/swaggerをインストールします。こちらをインストールすることにより、NestJSの実装部分にAPI仕様を追加することが可能になります。

1
$ npm install --save @nestjs/swagger

main.tsでSwaggerモジュールを初期化します。

./src/main.ts

1
  import { NestFactory } from '@nestjs/core';
2
 import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
3
  import { AppModule } from './app.module';
4

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

8
   const config = new DocumentBuilder().build();
9
   const document = SwaggerModule.createDocument(app, config);
10
   SwaggerModule.setup('api', app, document);
11

12
    await app.listen(3000);
13
}
14
bootstrap();

サーバーを起動して、Webブラウザからhttp://localhost:3000/apiにアクセスすると、以下のようなAPI仕様書が自動でできあがります。

API仕様書(初期化後)

前の節で作成したコードにAPI仕様の説明を加えていきます。
使用するデコレーターは@ApiOperation(), @ApiResponse(), @ApiProperty(), @ApiTags()などがあります。デコレーターとは、直訳すると「装飾」という意味となります。クラスをはじめ、メソッド・アクセサー・プロパティ・パラメーターに@デコレーター関数を付与することによって、関数の説明を追加で書き加えることが可能になります。一例で、API仕様書にタグを追加させるためのデコレーターである@ApiTags()とリンクしているapi-use-tags.decorator.d.tsの関数の中身を見てみたいと思います。

api-use-tags.decorator.d.ts

1
export declare function ApiTags(...tags: string[]): MethodDecorator & ClassDecorator;

ApiTagsの関数は、引数にstring型(配列)のtagsを持っていることが分かります。members.controller.tsに@ApiTags()のデコレーターを付与し、引数にAPIのタグとして/membersを指定してあげます。

./src/members/members.controller.ts

1
import {
2
  Controller,
3
  Get,
4
  Post,
5
  Body,
6
  Patch,
7
  Param,
8
  Delete,
9
} from '@nestjs/common';
10
  import { MembersService } from './members.service';
11
  import { CreateMemberDto } from './dto/create-member.dto';
12
  import { UpdateMemberDto } from './dto/update-member.dto';
13
 import { ApiTags } from '@nestjs/swagger';
14

15
  @Controller('members')
16
 @ApiTags('/members')
17
  export class MembersController {
18
    constructor(private readonly membersService: MembersService) {}
19

20
    @Post()
21
    create(@Body() createMemberDto: CreateMemberDto) {
22
      return this.membersService.create(createMemberDto);
23
    }
24

25
    @Get()
26
    findAll() {
27
     return this.membersService.findAll();
28
    }
29

30
    @Get(':id')
31
    findOne(@Param('id') id: string) {
32
      return this.membersService.findOne(+id);
33
    }
34

35
    @Patch(':id')
36
    update(@Param('id') id: string, @Body() updateMemberDto: UpdateMemberDto) {
37
      return this.membersService.update(+id, updateMemberDto);
38
    }
39

40
    @Delete(':id')
41
    remove(@Param('id') id: string) {
42
      return this.membersService.remove(+id);
43
    }
44
  }

再度サーバーを起動すると、APIのタグ一覧に/membersが追加されました。

API仕様書(タグを付けたバージョン)

ここから、具体的なAPI仕様を追加していきます。
今回は/membersの実装を主に使用するので、/membersのAPI仕様を追加したいと思います。

./src/main.ts

1
import { NestFactory } from '@nestjs/core';
2
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
3
import { AppModule } from './app.module';
4

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

8
  const config = new DocumentBuilder().build();
9
  const config = new DocumentBuilder()
10
   .setTitle('Members API docs')
11
   .setDescription('MembersのAPI仕様書です。')
12
   .setVersion('1.0')
13
   .build();
14
   const document = SwaggerModule.createDocument(app, config);
15
   SwaggerModule.setup('api', app, document);
16

17
  await app.listen(3000);
18
}
19
bootstrap();

./src/members/members.controller.ts

1
 import { Controller, Get, Post, Body, Patch, Param, Delete } from '@nestjs/common';
2
 import { MembersService } from './members.service';
3
 import { CreateMemberDto } from './dto/create-member.dto';
4
 import { UpdateMemberDto } from './dto/update-member.dto';
5
 import { ApiTags } from '@nestjs/swagger';
6
 import { ApiTags, ApiProduces, ApiOperation, ApiParam, ApiResponse } from '@nestjs/swagger';
7
 import { Member } from './entities/member.entity';
8

9
 @Controller('members')
10
 @ApiTags('/members')
11
 export class MembersController {
12
  constructor(private readonly membersService: MembersService) {}
13

14
 @Post()
15
 @ApiProduces('application/json; charset=utf-8')
16
 @ApiOperation({ summary: '単体登録API' })
17
 @ApiResponse({
18
   status: 201,
19
   description: '登録したメンバー設定を返却',
20
   type: Member,
21
 })
22
 create(@Body() createMemberDto: CreateMemberDto) {
23
    return this.membersService.create(createMemberDto);
24
  }
25

26
 @Get()
27
 @ApiProduces('application/json; charset=utf-8')
28
 @ApiOperation({ summary: '全体取得API' })
29
 @ApiResponse({
30
   status: 200,
31
   description: '登録済メンバー設定を複数返却',
32
   type: Member,
33
 })
34
  findAll() {
35
    return this.membersService.findAll();
36
  }
37

38
 @Get(':id')
39
 @ApiProduces('application/json; charset=utf-8')
40
 @ApiOperation({ summary: '単体取得API' })
41
 @ApiParam({
42
   name: 'id',
43
   type: Number,
44
   example: 1,
45
 })
46
 @ApiResponse({
47
   status: 200,
48
   description: '指定されたIDのメンバー設定を返却',
49
   type: Member,
50
 })
51
 findOne(@Param('id') id: string) {
52
   return this.membersService.findOne(+id);
53
 }
54

55
 @Patch(':id')
56
 @ApiProduces('application/json; charset=utf-8')
57
 @ApiOperation({ summary: '単体更新API' })
58
 @ApiParam({
59
   name: 'id',
60
   type: Number,
61
   example: 1,
62
 })
63
 @ApiResponse({
64
   status: 200,
65
   description: '更新後のメンバー設定を返却',
66
   type: Member,
67
 })
68
 update(@Param('id') id: string, @Body() updateMemberDto: UpdateMemberDto) {
69
   return this.membersService.update(+id, updateMemberDto);
70
 }
71

72
 @Delete(':id')
73
 @ApiProduces('application/json; charset=utf-8')
74
 @ApiOperation({ summary: '単体削除API' })
75
 @ApiParam({
76
   name: 'id',
77
   type: Number,
78
   example: 1,
79
 })
80
 @ApiResponse({
81
   status: 200,
82
   description: '削除されたメンバーの設定を返却',
83
   type: Member,
84
 })
85
 remove(@Param('id') id: string) {
86
   return this.membersService.remove(+id);
87
 }
88
}

エンティティにid、名前、年齢を持たせるようにします。

./src/members/entities/member.entity.ts

1
 import { ApiProperty } from '@nestjs/swagger';
2

3
  export class Member {
4
   @ApiProperty({ example: 1, description: 'メンバーID' })
5
   id: number;
6

7
  @ApiProperty({ example: 'アルファ太郎', description: 'メンバーの氏名' })
8
   name: string;
9

10
  @ApiProperty({ example: 25, description: 'メンバーの年齢' })
11
   age: number;
12
}

再度サーバーを起動すると、追加で加えた項目が更新されています。

API仕様書(単体取得-1) API仕様書(単体取得-2)

今回はステータスコードが200(成功)の場合のみ実装しましたが、他にも404や500エラー、バリデーションエラーなど、細かい仕様を追加することも可能です。

DreddでOpenAPI仕様書を元にAPIテストを行う

本章では、前章で作成したAPIサーバーとAPI仕様書をもとにAPIテストを行うためのスキーマの準備(Dreddで扱えるスキーマへの変換)、Dreddのインストール、実際にコマンドを入力して試験を行います。その後、APIテスト結果・API仕様書をもとに実装を作成し、仕様書と実装の間の差分が無くなるようにしていきます。

DreddによるAPIテストの最終目標

事前準備

NestJSのアプリ起動時にopenapi.ymlが作成されるようにする

APIテストを行うためには、YAMLやJSONで書かれたスキーマファイル、すなわちAPIの仕様が書かれた構造ファイルが必要になります。前の章の実装では、スキーマファイルが生成されていないため、ファイル出力をする実装を追加して、自動でmember-manageディレクトリ内にYAML形式のスキーマファイルを出力するようにします。

./src/main.ts

1
import { NestFactory } from '@nestjs/core';
2
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
3
import { AppModule } from './app.module';
4
import * as path from 'path';
5
import { writeFileSync } from 'fs';
6
import { dump } from 'js-yaml';
7

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

11
   const config = new DocumentBuilder()
12
     .setTitle('Members API docs')
13
     .setDescription('MembersのAPI仕様書です。')
14
     .setVersion('1.0')
15
     .build();
16
   const document = SwaggerModule.createDocument(app, config);
17
   SwaggerModule.setup('api', app, document);
18
  const outputPath = path.resolve(process.cwd(), 'openapi.yml');
19
  writeFileSync(outputPath, dump(document, {}));
20

21
  await app.listen(3000);
22
}
23
bootstrap();

上記を追記した上で、再びサーバーを起動すると、member-manageディレクトリ内にopenapi.ymlが自動生成されます。Dreddは、API仕様としてこのファイルをベースに試験していくことになります。

./openapi.yml

クリックして開く／閉じる

1
openapi: 3.0.0
2
paths:
3
  /:
4
    get:
5
      operationId: AppController_getHello
6
      parameters: []
7
      responses:
8
        '200':
9
          description: ''
10
  /members:
11
    post:
12
      operationId: MembersController_create
13
      summary: 単体登録API
14
      parameters: []
15
      requestBody:
16
        required: true
17
        content:
18
          application/json:
19
            schema:
20
              $ref: '#/components/schemas/CreateMemberDto'
21
      responses:
22
        '201':
23
          description: 登録したメンバー設定を返却
24
          content:
25
            application/json; charset=utf-8:
26
              schema:
27
                $ref: '#/components/schemas/Member'
28
      tags: &ref_0
29
        - /members
30
    get:
31
      operationId: MembersController_findAll
32
      summary: 全体取得API
33
      parameters: []
34
      responses:
35
        '200':
36
          description: 登録済メンバー設定を複数返却
37
          content:
38
            application/json; charset=utf-8:
39
              schema:
40
                $ref: '#/components/schemas/Member'
41
      tags: *ref_0
42
  /members/{id}:
43
    get:
44
      operationId: MembersController_findOne
45
      summary: 単体取得API
46
      parameters:
47
        - name: id
48
          required: true
49
          in: path
50
          example: 1
51
          schema:
52
            type: number
53
      responses:
54
        '200':
55
          description: 指定されたIDのメンバー設定を返却
56
          content:
57
            application/json; charset=utf-8:
58
              schema:
59
                $ref: '#/components/schemas/Member'
60
      tags: *ref_0
61
    patch:
62
      operationId: MembersController_update
63
      summary: 単体更新API
64
      parameters:
65
        - name: id
66
          required: true
67
          in: path
68
          example: 1
69
          schema:
70
            type: number
71
      requestBody:
72
        required: true
73
        content:
74
          application/json:
75
            schema:
76
              $ref: '#/components/schemas/UpdateMemberDto'
77
      responses:
78
        '200':
79
          description: 更新後のメンバー設定を返却
80
          content:
81
            application/json; charset=utf-8:
82
              schema:
83
                $ref: '#/components/schemas/Member'
84
      tags: *ref_0
85
    delete:
86
      operationId: MembersController_remove
87
      summary: 単体削除API
88
      parameters:
89
        - name: id
90
          required: true
91
          in: path
92
          example: 1
93
          schema:
94
            type: number
95
      responses:
96
        '200':
97
          description: 削除されたメンバーの設定を返却
98
          content:
99
            application/json; charset=utf-8:
100
              schema:
101
                $ref: '#/components/schemas/Member'
102
      tags: *ref_0
103
info:
104
  title: Members API docs
105
  description: MembersのAPI仕様書です。
106
  version: '1.0'
107
  contact: {}
108
tags: []
109
servers: []
110
components:
111
  schemas:
112
    CreateMemberDto:
113
      type: object
114
      properties: {}
115
    Member:
116
      type: object
117
      properties:
118
        id:
119
          type: number
120
          example: 1
121
          description: メンバーID
122
        name:
123
          type: string
124
          example: アルファ太郎
125
          description: メンバーの氏名
126
        age:
127
          type: number
128
          example: 25
129
          description: メンバーの年齢
130
      required:
131
        - id
132
        - name
133
        - age
134
    UpdateMemberDto:
135
      type: object
136
      properties: {}

Dreddの設定ファイル(dredd.yml)を準備してopenapi.ymlを指定

実際に試験するサーバーや、使用されている言語、API仕様書などを指定する設定ファイルを作成します。こちらも作成コマンドを入力し、質問に答えていくことで自動でYAMLファイルが出力されます。
まず初めに、以下のコマンドを入力してパッケージをインストールします。

1
$ npm install -g dredd

次に、dredd initと入力し、APIテストの元となるdredd.ymlを生成します。 dredd initでは、対話形式で入力することができます。

1
$ dredd init
2
? Location of the API description document (openapi.yml) (node:16336) Warning: Accessing non-existent property 'padLevels' of module exports inside circular dependency
3
(Use `node --trace-warnings ...` to show where the warning was created)
4
? Location of the API description document openapi.yml
5
? Command to start the API server under test npm start
6
? Host of the API under test http://localhost:3000/
7
? Do you want to use hooks to customize Dredd's behavior? Yes
8
? Programming language of the hooks JavaScript
9
? Do you want to report your tests to the Apiary inspector? Yes
10
? Enter Apiary API key (leave empty for anonymous, disposable test reports)
11
? Dredd is best served with Continuous Integration. Do you want to create CI configuration? No

完了すると、dredd.ymlが生成されます。
これで下準備は完了です。

./dredd.yml

クリックして開く／閉じる

1
color: true
2
dry-run: null
3
hookfiles: null
4
language: nodejs
5
require: null
6
server: npm start
7
server-wait: 3
8
init: false
9
custom: {}
10
names: false
11
only: []
12
reporter: apiary
13
output: []
14
header: []
15
sorted: false
16
user: null
17
inline-errors: false
18
details: false
19
method: []
20
loglevel: warning
21
path: []
22
hooks-worker-timeout: 5000
23
hooks-worker-connect-timeout: 1500
24
hooks-worker-connect-retry: 500
25
hooks-worker-after-connect-wait: 100
26
hooks-worker-term-timeout: 5000
27
hooks-worker-term-retry: 500
28
hooks-worker-handler-host: 127.0.0.1
29
hooks-worker-handler-port: 61321
30
config: ./dredd.yml
31
blueprint: openapi.yml
32
endpoint: 'http://localhost:3000/'

実施手順

次からは実際にAPIテストを行っていきます。ターミナル上で以下のコマンドを入力します。

1
$ dredd

dredd.ymlでサーバーをnpm startに設定したため、自動でhttp://localhost:3000/が立ち上がり、ターミナル上に以下のログが出力されます。

1
> member-manage@0.0.1 start
2
> nest start
3

4
[Nest] 17760  - 2022/12/23 15:03:14     LOG [NestFactory] Starting Nest application...
5
[Nest] 17760  - 2022/12/23 15:03:14     LOG [InstanceLoader] AppModule dependencies initialized +25ms
6
[Nest] 17760  - 2022/12/23 15:03:14     LOG [InstanceLoader] MembersModule dependencies initialized +0ms
7
[Nest] 17760  - 2022/12/23 15:03:19     LOG [RoutesResolver] AppController {/}: +4981ms
8
[Nest] 17760  - 2022/12/23 15:03:19     LOG [RouterExplorer] Mapped {/, GET} route +2ms
9
[Nest] 17760  - 2022/12/23 15:03:19     LOG [RoutesResolver] MembersController {/members}: +1ms
10
[Nest] 17760  - 2022/12/23 15:03:19     LOG [RouterExplorer] Mapped {/members, POST} route +2ms
11
[Nest] 17760  - 2022/12/23 15:03:19     LOG [RouterExplorer] Mapped {/members, GET} route +1ms
12
[Nest] 17760  - 2022/12/23 15:03:19     LOG [RouterExplorer] Mapped {/members/:id, GET} route +1ms
13
[Nest] 17760  - 2022/12/23 15:03:19     LOG [RouterExplorer] Mapped {/members/:id, PATCH} route +1ms
14
[Nest] 17760  - 2022/12/23 15:03:19     LOG [RouterExplorer] Mapped {/members/:id, DELETE} route +2ms
15
[Nest] 17760  - 2022/12/23 15:03:19     LOG [NestApplication] Nest application successfully started +3ms

しばらく待つと、ターミナル上に結果が返ってきます。

API試験結果(一部抜粋)

1
pass: GET (200) / duration: 53ms
2
fail: POST (201) /members duration: 30ms
3
fail: GET (200) /members duration: 9ms
4
fail: GET (200) /members/1 duration: 9ms
5
fail: PATCH (200) /members/1 duration: 8ms
6
fail: DELETE (200) /members/1 duration: 8ms

APIのテストの結果で、passがAPI仕様書通りの実装であるという意味になり、failがAPIの仕様書通りの実装ではないという意味になります。
6項目中5項目がAPI仕様通りの実装ではないことを確認しましたので、今回はそのうちの単体取得(GET)のAPIの実装を、API仕様書通りの実装に修正したいと思います。

単体取得(GET)のAPI仕様書では、application/json; charset=utf-8が返ることを想定していますが、自動生成されたコードのままだとtext/html; charset=utf-8でレスポンスされる実装のためエラーが返ってくるようになります。

エラー出力結果(一部抜粋)

クリックして開く／閉じる

1
fail: GET (200) /members/1 duration: 9ms
2
info: Displaying failed tests...
3

4

5
fail: GET (200) /members/1 duration: 9ms
6
fail: headers: At '/content-type' No enum match for: "text/html; charset=utf-8"
7
body: Can't validate actual media type 'text/plain' against the expected media type 'application/json'.
8

9
request:
10
method: GET
11
uri: /members/1
12
headers:
13
    Accept: application/json; charset=utf-8
14
    User-Agent: Dredd/14.1.0 (Windows_NT 10.0.19044; x64)
15

16
body:
17

18

19

20
expected:
21
headers:
22
    Content-Type: application/json; charset=utf-8
23

24
body:
25
{
26
  "id": 1,
27
  "name": "アルファ太郎",
28
  "age": 25
29
}
30
statusCode: 200
31

32

33
actual:
34
statusCode: 200
35
headers:
36
    x-powered-by: Express
37
    content-type: text/html; charset=utf-8
38
    content-length: 31
39
    etag: W/"1f-cxD8UaISAOaz8Awh05Vrp6LAZ28"
40
    date: Fri, 23 Dec 2022 06:03:20 GMT
41
    connection: close
42

43
bodyEncoding: utf-8
44
body:
45
This action returns a #1 member
46

47

48

49
complete: 1 passing, 5 failing, 0 errors, 0 skipped, 6 total
50
complete: Tests took 11765ms

このように、API仕様書と違う実装になっていることが分かるようになります。

./src/members/members.service.ts

1
  //返却値のcontent-typeがtext/htmlである
2
  findOne(id: number) {
3
    return `This action returns a #${id} member`;
4
  }

ファイルの種類が異なる例

また、レスポンスヘッダー以外にも、レスポンスのボディーの内容がAPI仕様書と異なっている場合にもエラーが返るようになっています。
今度は、レスポンスのファイルの種類をJSONに修正し、データの部分の年齢をあえて削除して、API仕様とは異なるようにしてみます。members.service.tsの返却値は、members.jsonのデータに基づき、指定されたidの番号の情報(id・名前・年齢)を返す処理に修正しています。

./src/members/members.service.ts

1
 import { Injectable } from '@nestjs/common';
2
 import { CreateMemberDto } from './dto/create-member.dto';
3
 import { UpdateMemberDto } from './dto/update-member.dto';
4
import { promises } from 'fs';
5
const { readFile } = promises;
6

7
@Injectable()
8
export class MembersService {
9
  create(createMemberDto: CreateMemberDto) {
10
    return 'This action adds a new member';
11
  }
12

13
  findAll() {
14
    return `This action returns all members`;
15
  }
16

17
 findOne(id: number) {
18
 async findOne(id: number) {
19
    return `This action returns a #${id} member`;
20
    const contents = await readFile('src/members/members.json', 'utf-8');
21
    const json = JSON.parse(contents);
22
    let tmp = null;
23

24
    json.members.forEach((member: { id: number }) => {
25
      if (member.id == id) {
26
        tmp = member;
27
      }
28
    });
29
    return tmp;
30
  }
31

32
    update(id: number, updateMemberDto: UpdateMemberDto) {
33
    return `This action updates a #${id} member`;
34
  }
35

36
  remove(id: number) {
37
    return `This action removes a #${id} member`;
38
  }
39
}

./src/members/members.json

1
 {
2
     "members": [
3
       { "id": 1, "name": "テスト次郎" },
4
       { "id": 2, "name": "テック三郎" },
5
       { "id": 3, "name": "ブログ四郎" }
6
     ]
7
 }

必須要件である年齢が見つかりませんとエラーが返ってきました。

1
info: Displaying failed tests...
2
fail: GET (200) /members/1 duration: 66ms
3
fail: body: At '/age' Missing required property: age

レスポンスのボディの形式が異なる

エラー出力結果(一部抜粋)

クリックして開く／閉じる

1
fail: GET (200) /members/1 duration: 66ms
2
info: Displaying failed tests...
3

4
fail: GET (200) /members/1 duration: 16ms
5
fail: body: At '/age' Missing required property: age
6

7
request:
8
method: GET
9
uri: /members/1
10
headers:
11
    Accept: application/json; charset=utf-8
12
    User-Agent: Dredd/14.1.0 (Windows_NT 10.0.19044; x64)
13

14
body:
15

16

17

18
expected:
19
headers:
20
    Content-Type: application/json; charset=utf-8
21

22
body:
23
{
24
  "id": 1,
25
  "name": "アルファ太郎",
26
  "age": 25
27
}
28
statusCode: 200
29

30

31
actual:
32
statusCode: 200
33
headers:
34
    x-powered-by: Express
35
    content-type: application/json; charset=utf-8
36
    content-length: 33
37
    etag: W/"21-YclVsVtE1CMIGd4OlyBgxwhzPag"
38
    date: Fri, 23 Dec 2022 06:44:31 GMT
39
    connection: close
40

41
bodyEncoding: utf-8
42
body:
43
{
44
  "id": 1,
45
  "name": "テスト次郎"
46
}
47

48

49

50

51
complete: 1 passing, 5 failing, 0 errors, 0 skipped, 6 total
52
complete: Tests took 11662ms

最後はテストが通るように、members.jsonに年齢の項目を追加して修正します。

./src/members/members.json

1
{
2
    "members": [
3
      { "id": 1, "name": "テスト次郎", "age": 30 },
4
      { "id": 2, "name": "テック三郎", "age": 28 },
5
      { "id": 3, "name": "ブログ四郎", "age": 26 }
6
    ]
7
}

APIテストの結果がpassとなり、API仕様通りの実装であることを確認できました。

1
pass: GET (200) /members/1 duration: 124ms
2
complete: 2 passing, 4 failing, 0 errors, 0 skipped, 6 total
3
complete: Tests took 12110ms

それぞれの利点について

今回NestJSおよびDreddを試してみて感じたメリットについて紹介したいと思います。

NestJSを使ってOpenAPI仕様書を作成するメリット

普通にOpenAPI仕様書をYAML形式で書くより楽

今回使用したSwaggerでは、YAML形式やJSON形式の記述に対応しています。ですので手動で記述することも可能です。小規模なプログラムであればそれでも構わないとは思いますが、大規模なシステムであったり、万が一APIの仕様に変更が生じた際の修正の手間を考えると、ファイル出力のプログラムを追加してAPI仕様書作成・更新を自動化させる方が圧倒的に楽であるといえます。

NestJSに組み込まれているためセットアップが容易(main.tsで指定するだけ)

実際に導入してみて感じたのがAPI仕様書を作成するまでのハードルの低さでした。今回この記事を執筆するにあたり、初めてSwaggerを触りましたが、パッケージインストールとDocumentBuilderを設定してあげるだけですので、躓くことなく簡単に作成することができました。

Dreddを用いるメリット

Dreddを使う利点は、別途APIテストコードを書かなくてもある程度API仕様書に沿った試験を自動的に行うことができる点です。
また、自動でAPI仕様書を読み込んでくれるため、正確に試験を実施することが可能となります。

おわりに

今回は、APIサーバー構築方法と、OpenAPI仕様書作成・APIテストを自動で行ってくれるツールについて紹介しました。
手動で行うよりも効率よく開発が行えると思いますので、みなさんもぜひ試していただければと思います。

参考サイト

記事をシェアする