Membuat Dokumentasi API Menggunakan Swagger di NestJS

Halo Talenta Digital, gimana kabarnya hari ini? Semoga masih semangat belajar ya. Kali ini kita akan belajar bagaimana membuat dokumentasi API di NestJS menggunakan Swagger.

Dokumentasi API adalah bagian yang sangat penting dari sebuah server API. Dokumentasi API menjelasakan bagaimana cara menggunakan API endpoint yang disediakan, termasuk seperti apa data yang harus dikirimkan ketika membuat request, serta seperti apa data yang akan dikembalikan sebagai response. Tanpa dokumentasi API yang jelas, API Server yang kita buat akan sulit untuk digunakan oleh orang lain yang ingin melakukan integrasi.

Swagger

Swagger adalah sebuah kerangka kerja open source yang digunakan untuk merancang, membangun, dan mendokumentasikan API (Application Programming Interface). Swagger memungkinkan pengembang untuk mendefinisikan spesifikasi API dalam format yang dapat dibaca manusia dan mesin, seperti JSON atau YAML. Dengan Swagger, pengembang dapat menggambarkan endpoint-endpoint API, parameter-parameter yang diperlukan, respons yang diharapkan, serta menjelaskan bagaimana berinteraksi dengan API tersebut. Dokumentasi yang dihasilkan oleh Swagger dapat membantu pengembang lain untuk memahami dan menggunakan API dengan lebih mudah dan efisien.

NestJs

NestJS adalah sebuah kerangka kerja backend Node.js yang berbasis TypeScript, yang dirancang untuk membangun aplikasi server-side yang efisien, modular, dan mudah diorganisasi. Dengan menggunakan pendekatan berorientasi objek dan pola desain yang terinspirasi dari Angular, NestJS menyediakan struktur yang jelas dan terstruktur untuk membangun aplikasi server yang skalabel dan mudah diuji. Dengan dukungan penuh untuk dependency injection, middleware, routing, pemetaan objek-relasional (ORM), dan banyak lagi, NestJS memungkinkan pengembang untuk dengan cepat dan mudah mengembangkan aplikasi backend yang kuat dan kompleks dengan standar industri yang tinggi.

Membuat Dokumentasi API di NestJS Menggunakan Swagger

Mempersiapkan Project

Untuk mempermudah dan mempercepat tutorial kita, saya sudah memperisapkan project starter untuk tutorial di postingan ini. Kamu bisa clone repository GitHub berikut:

https://github.com/ruangdeveloper/nestjs-swagger

Pada repository tersebut sudah terdapat beberapa file untuk contoh sebuah REST API.

Install Swagger

NestJS telah mempersiapkan package yang memudahkan kita untuk membuat dokumentasi API menggunakan Swagger. Kita akan menginstall package bernama @nestjs/swagger.

npm install --save @nestjs/swagger

Setelah installasi selesai, kita perlu menginisialisasi Swagger di dalam file main.ts. Buka file tersebut, kemudian edit menjadi seperti berikut:

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

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

  const swaggerConfig = new DocumentBuilder()
    .setTitle("Notes API")
    .setDescription("Notes API description")
    .setVersion("1.0")
    .build();

  const swaggerDocument = SwaggerModule.createDocument(app, swaggerConfig);

  SwaggerModule.setup("docs", app, swaggerDocument);

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

Dalam baris kode const swaggerConfig = new DocumentBuilder().setTitle(‘Notes API’).setDescription(‘Notes API description’).setVersion(‘1.0’).build();, kita menggunakan objek DocumentBuilder dari Swagger untuk mengonfigurasi dokumen Swagger. Dalam contoh ini, kita menetapkan judul API sebagai “Notes API”, deskripsi API sebagai “Notes API description”, dan versi API sebagai “1.0”. Metode build() digunakan untuk menghasilkan konfigurasi yang telah dibuat.

Kemudian, pada baris const swaggerDocument = SwaggerModule.createDocument(app, swaggerConfig);, kita menggunakan metode SwaggerModule.createDocument untuk membuat dokumen Swagger berdasarkan konfigurasi yang telah kita buat sebelumnya. Dokumen Swagger ini akan digunakan untuk menghasilkan dokumentasi API.

Pada baris terakhir SwaggerModule.setup(‘docs’, app, swaggerDocument);, kita menggunakan metode SwaggerModule.setup untuk menyiapkan antarmuka pengguna Swagger di endpoint ‘/docs’ pada aplikasi NestJS. Ini berarti kita dapat mengakses dokumentasi API Swagger dengan menjalankan aplikasi dan membuka ‘/docs’ pada browser. Antarmuka pengguna Swagger akan menampilkan informasi dan dokumentasi terkait API yang telah didefinisikan.

Setelah file main.ts diupdate, sekarang mari kita coba jalankan project dengan command npm run start:dev kemudian buka url http://127.0.0.1:3000/docs di browser. Berikut ini adalah hasilnya:

Ini belum selesai ya, kalau kita lihat detail dari salah satu endpoint, masih belum ada informasi response atau requestnya, seperti ini:

Konfigurasi Dokumentasi Swagger

Modifikasi file src/app.request.ts menjadi seperti berikut:

import { ApiProperty } from "@nestjs/swagger";

export class CreateNoteRequest {
  @ApiProperty()
  title: string;

  @ApiProperty()
  description: string;
}

export class UpdateNoteRequest {
  @ApiProperty()
  title: string;

  @ApiProperty()
  description: string;
}

Modifikasi file src/app.entity.ts menjadi seperti berikut:

import { ApiProperty } from "@nestjs/swagger";

export class Note {
  @ApiProperty()
  title: string;

  @ApiProperty()
  description: string;
}

Modifilasi file src/app.response.ts menjadi seperti berikut:

import { ApiProperty } from "@nestjs/swagger";
import { Note } from "./app.entity";

export class ApiResponse<T> {
  data: T;
  message: string;
}

export class NoteIndexResponseExample {
  @ApiProperty({ type: [Note] })
  data: Array<Note>;

  @ApiProperty()
  message: string;
}

export class NoteShowResponseExample {
  @ApiProperty({ type: Note })
  data: Note;

  @ApiProperty()
  message: string;
}

export class NoteStoreResponseExample {
  @ApiProperty({ type: Note })
  data: Note;

  @ApiProperty()
  message: string;
}

export class NoteUpdateResponseExample {
  @ApiProperty({ type: Note })
  data: Note;

  @ApiProperty()
  message: string;
}

Decorator @ApiProperty() digunakan dalam kode di atas untuk memberikan informasi tambahan kepada Swagger tentang properti yang terdapat dalam kelas CreateNoteRequest dan UpdateNoteRequest.

Dalam contoh tersebut, decorator @ApiProperty() diterapkan pada properti title dan description di kedua kelas. Decorator ini memberikan informasi kepada Swagger bahwa properti-properti ini adalah bagian dari skema (schema) yang terkait dengan request atau respons API yang terkait.

Decorator @ApiProperty() ini memungkinkan kita untuk memberikan konfigurasi tambahan, seperti tipe data, deskripsi, nama, contoh, dan banyak lagi, untuk setiap properti dalam kelas tersebut. Informasi ini akan digunakan oleh Swagger untuk menghasilkan dokumentasi yang lebih kaya dan lebih informatif.

Dengan menggunakan decorator @ApiProperty(), kita dapat secara eksplisit menggambarkan properti-properti yang ada dalam request dan respons API kita, sehingga memudahkan pengguna API untuk memahami format dan tipe data yang diharapkan untuk setiap properti.

Modifikasi file src/app.controller.ts menjadi seperti berikut:

import { Body, Controller, Delete, Get, Post, Put } from "@nestjs/common";
import { AppService } from "./app.service";
import { CreateNoteRequest, UpdateNoteRequest } from "./app.request";
import { Note } from "./app.entity";
import {
  ApiResponse,
  NoteIndexResponseExample,
  NoteShowResponseExample,
  NoteStoreResponseExample,
  NoteUpdateResponseExample,
} from "./app.response";
import { ApiOkResponse, ApiTags } from "@nestjs/swagger";

@ApiTags("Note Endpoints")
@Controller("notes")
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  @ApiOkResponse({
    type: () => NoteIndexResponseExample,
  })
  index(): ApiResponse<Array<Note>> {
    const notes = this.appService.getAllNotes();

    return {
      data: notes,
      message: "Notes retrieved successfully",
    };
  }

  @Get(":id")
  @ApiOkResponse({
    type: () => NoteShowResponseExample,
  })
  show(): ApiResponse<Note> {
    const note = this.appService.getNote();

    return {
      data: note,
      message: "Note retrieved successfully",
    };
  }

  @Post()
  @ApiOkResponse({
    type: () => NoteStoreResponseExample,
  })
  store(@Body() body: CreateNoteRequest): ApiResponse<Note> {
    const note = this.appService.createNote(body.title, body.description);

    return {
      data: note,
      message: "Note created successfully",
    };
  }

  @Put(":id")
  @ApiOkResponse({
    type: () => NoteUpdateResponseExample,
  })
  update(@Body() body: UpdateNoteRequest): ApiResponse<Note> {
    const note = this.appService.updateNote(body.title, body.description);

    return {
      data: note,
      message: "Note updated successfully",
    };
  }

  @Delete(":id")
  destroy(): ApiResponse<null> {
    const result = this.appService.deleteNote();

    return {
      data: null,
      message: result.message,
    };
  }
}

Pada controller, terdapat dua jenis decorator Swagger yang digunakan, yaitu @ApiTags() dan @ApiOkResponse().

1. @ApiTags('Note Endpoints'): Decorator @ApiTags() digunakan untuk memberikan tag atau label pada endpoint atau grup endpoint tertentu. Dalam contoh tersebut, decorator tersebut ditempatkan di atas AppController class dengan nilai 'Note Endpoints', yang berarti semua endpoint dalam controller tersebut akan memiliki tag “Note Endpoints”. Tags ini akan digunakan oleh Swagger untuk mengelompokkan dan mengorganisir endpoint-endpoint yang ada dalam dokumentasi yang dihasilkan.

2. @ApiOkResponse({ type: () => NoteIndexResponseExample }): Decorator @ApiOkResponse() digunakan untuk memberikan respon sukses (HTTP status code 200) dari sebuah endpoint. Dalam contoh tersebut, decorator tersebut ditempatkan di atas method index() dalam AppController class. Parameter yang dilewatkan ke decorator ini adalah sebuah objek yang mendefinisikan tipe respon yang diharapkan. Properti type diberikan dengan fungsi arrow () => NoteIndexResponseExample, yang berarti tipe respon yang diharapkan adalah NoteIndexResponseExample. Tipe ini akan digunakan oleh Swagger untuk menghasilkan skema respon dalam dokumentasi.

Decorator @ApiTags() digunakan untuk memberikan tag atau label pada grup endpoint, sementara decorator @ApiOkResponse() digunakan untuk mendefinisikan tipe respon sukses dari sebuah endpoint dalam dokumentasi Swagger.

Hasil

Setelah selesai modifikasi, kita bisa periksa kembali dokumentasi swagger kita di browser, jika semuanya benar, maka hasilnya lebih kurang akan terlihat seperti ini: