Membangun Dokumentasi API Menggunakan Swagger di NestJS

Halo Bakat Digital, gimana kabarnya hari ini? Semoga Lagi semangat belajar ya. Kali ini kita akan belajar bagaimana Membangun dokumentasi API di NestJS menggunakan Swagger.

Dokumentasi API adalah bagian yang sangat Krusial dari sebuah server API. Dokumentasi API menjelasakan bagaimana Metode menggunakan API endpoint yang disediakan, termasuk seperti apa data yang harus dikirimkan ketika Membangun request, serta seperti apa data yang akan dikembalikan sebagai response. Tanpa dokumentasi API yang Terang, API Server yang kita buat akan sulit Kepada digunakan oleh orang lain yang Mau melakukan integrasi.

Swagger

Swagger adalah sebuah kerangka kerja open source yang digunakan Kepada merancang, membangun, dan mendokumentasikan API (Application Programming Interface). Swagger memungkinkan pengembang Kepada mendefinisikan spesifikasi API dalam format yang dapat dibaca Sosok 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 Kepada memahami dan menggunakan API dengan lebih mudah dan efisien.

NestJs

NestJS adalah sebuah kerangka kerja backend Node.js yang berbasis TypeScript, yang dirancang Kepada 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 Terang dan terstruktur Kepada membangun aplikasi server yang skalabel dan mudah diuji. Dengan dukungan penuh Kepada dependency injection, middleware, routing, pemetaan objek-relasional (ORM), dan banyak Kembali, NestJS memungkinkan pengembang Kepada dengan Segera dan mudah mengembangkan aplikasi backend yang kuat dan kompleks dengan standar industri yang tinggi.

Membangun Dokumentasi API di NestJS Menggunakan Swagger

Mempersiapkan Project

Kepada mempermudah dan mempercepat tutorial kita, saya sudah memperisapkan project starter Kepada tutorial di postingan ini. Engkau Bisa clone repository GitHub berikut:

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

Pada repository tersebut sudah terdapat beberapa file Kepada Misalnya sebuah REST API.

Install Swagger

NestJS telah mempersiapkan package yang memudahkan kita Kepada Membangun 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 Kepada mengonfigurasi Arsip Swagger. Dalam Misalnya ini, kita menetapkan judul API sebagai “Notes API”, deskripsi API sebagai “Notes API description”, dan versi API sebagai “1.0”. Metode build() digunakan Kepada menghasilkan konfigurasi yang telah dibuat.

READ Kelebihan, Teladan, dan Perbedaannya dengan GUI

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

Pada baris terakhir SwaggerModule.setup(‘docs’, app, swaggerDocument);, kita menggunakan metode SwaggerModule.setup Kepada 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, Lagi belum Terdapat 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 ApiResponseT> {
  data: T;
  message: string;
}

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

  @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 Kepada memberikan informasi tambahan kepada Swagger tentang properti yang terdapat dalam kelas CreateNoteRequest dan UpdateNoteRequest.

READ Pengertian, Jenis, Fungsi & Misalnya

Dalam Misalnya 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 Kepada memberikan konfigurasi tambahan, seperti tipe data, deskripsi, nama, Misalnya, dan banyak Kembali, Kepada setiap properti dalam kelas tersebut. Informasi ini akan digunakan oleh Swagger Kepada menghasilkan dokumentasi yang lebih kaya dan lebih informatif.

Dengan menggunakan decorator @ApiProperty(), kita dapat secara eksplisit menggambarkan properti-properti yang Terdapat dalam request dan respons API kita, sehingga memudahkan pengguna API Kepada memahami format dan tipe data yang diharapkan Kepada 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(): ApiResponseArrayNote>> {
    const notes = this.appService.getAllNotes();

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

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

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

  @Post()
  @ApiOkResponse({
    type: () => NoteStoreResponseExample,
  })
  store(@Body() body: CreateNoteRequest): ApiResponseNote> {
    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): ApiResponseNote> {
    const note = this.appService.updateNote(body.title, body.description);

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

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

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

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

@ApiTags('Note Endpoints'):
Decorator @ApiTags() digunakan Kepada memberikan tag atau label pada endpoint atau grup endpoint tertentu. Dalam Misalnya tersebut, decorator tersebut ditempatkan di atas AppController class dengan nilai 'Note Endpoints', yang berarti Segala endpoint dalam controller tersebut akan Mempunyai tag “Note Endpoints”. Tags ini akan digunakan oleh Swagger Kepada mengelompokkan dan mengorganisir endpoint-endpoint yang Terdapat dalam dokumentasi yang dihasilkan.
@ApiOkResponse({ type: () => NoteIndexResponseExample }):
Decorator @ApiOkResponse() digunakan Kepada memberikan respon sukses (HTTP status code 200) dari sebuah endpoint. Dalam Misalnya 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 Kepada menghasilkan skema respon dalam dokumentasi.

READ 4 Langkah Mengukur Kinerja Digital Marketing yang Betul

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

Hasil

Setelah selesai modifikasi, kita Bisa periksa kembali dokumentasi swagger kita di browser, Kalau semuanya Betul, maka hasilnya lebih kurang akan terlihat seperti ini: