Swagger adalah kerangka kerja sumber terbuka gratis untuk membuat dokumentasi API yang interaktif dan ramah pengguna. Ini menghasilkan halaman web interaktif yang memungkinkan Anda menguji API dengan berbagai input.

Swagger mendukung payload JSON dan XML. Dokumentasi yang dihasilkannya cocok untuk digunakan oleh pengembang dan non-pengembang.

Anda dapat mendokumentasikan API web NestJS Anda melalui Swagger menggunakan dekorator sederhana, tanpa harus meninggalkan IDE Anda.

Langkah 1: Membuat API

Sebelum memulai, Anda harus membuat API demo yang akan dibuat oleh Swagger dokumentasinya.

Anda akan membuat API demo dari awal menggunakan NestJS CLI.

Pertama, buat proyek NestJS baru dengan menjalankan:

sarang baru <nama-proyek-Anda>

Kemudian, ubah direktori ke proyek yang sudah Anda buat dengan menjalankan:

CD <nama-proyek-Anda>

Selanjutnya, Anda akan membuat REST API dengan CLI dengan menjalankan:

sarang menghasilkan demo sumber daya --tidak ada spesifikasi

Anda akan melihat kueri yang menanyakan, "Lapisan transport apa yang Anda gunakan?" Pilih REST API.

instagram viewer

Anda akan melihat kueri lain yang menanyakan, "Apakah Anda ingin membuat titik masuk CRUD?" Jenis kamu dan pukul Memasuki.

Perintah di atas menghasilkan API REST yang berfungsi penuh dengan titik akhir CRUD dan tanpa file unit test. Oleh karena itu, --tidak ada spesifikasi tandai pada perintah di atas.

Langkah 2: Instal Swagger

Instal Swagger dan perpustakaan Express UI-nya dengan menjalankan:

npm Install--save @nestjs/swagger swagger-ui-express

Langkah 3: Konfigurasikan Swagger

di kamu main.ts file, impor SwaggerModul dan Pembuat Dokumen dari @nestjs/swagger.

DocumentBuilder membantu dalam penataan dokumen dasar. Ini menyediakan beberapa metode yang dapat Anda rantai bersama dan tutup dengan membangun metode.

Metode ini memungkinkan konfigurasi banyak atribut, seperti judul, deskripsi, dan versi.

Membuat konfigurasi variabel objek di Anda bootstrap fungsi seperti:

konstan konfigurasi = baru Pembuat Dokumen()
 .setTitle('API Demo')
 .setDescription('A Demo API dengan fungsionalitas CRUD')
 .setVersi('1.0')
 .membangun();

Sebuah instance baru dari DocumentBuilder membuat dokumen dasar yang cocok dengan Spesifikasi OpenAPI. Anda kemudian dapat menggunakan instance ini untuk mengatur judul, deskripsi, dan versi melalui metode yang sesuai.

Selanjutnya, Anda harus membuat dokumen lengkap dengan semua rute HTTP yang ditentukan menggunakan dokumen dasar.

Untuk melakukan ini, hubungi buatDokumen metode pada SwaggerModule. createDocument menerima dua argumen: instance aplikasi dan objek opsi Swagger. Simpan hasil panggilan ini dalam variabel untuk digunakan nanti:

konstandokumen = SwaggerModule.createDocument (aplikasi, konfigurasi);

Selanjutnya, hubungi mempersiapkan metode pada SwaggerModule. Metode penyiapan mengambil tiga argumen:

  1. Jalur UI Swagger. Dengan konvensi, Anda dapat menggunakan "api".
  2. Contoh aplikasi
  3. Dokumen lengkap

Selain itu, metode penyiapan mengambil objek opsi opsional. Melihat Dokumentasi NestJS tentang opsi dokumen Swagger untuk mempelajari lebih lanjut tentangnya.

Seperti:

SwaggerModule.setup('api', aplikasi, dokumen);

Mulai aplikasi Anda dan pergi ke http://localhost:/api

Anda akan melihat UI Swagger ditampilkan di halaman.

Gambar di atas adalah tampilan default dari UI Swagger, dengan semua rute HTTP di pengontrol Anda ditentukan. Anda harus menyesuaikannya agar sesuai dengan fungsionalitas API Anda.

Langkah 4: Sesuaikan Properti API

Secara default, Swagger mengawali seluruh bagian rute HTTP dengan judul yang bertuliskan "default." Anda dapat mengubahnya dengan memberi anotasi pada kelas pengontrol Anda dengan @ApiTags dekorator dan meneruskan tag pilihan Anda sebagai argumen.

Seperti:

// demo.controller.ts
impor { Tag Api } dari '@nestjs/swagger';
@ApiTags('Demo')
@Pengendali('demo')
eksporkelas Pengendali Demo {

Bagian Skema berisi objek Transfer data di API Anda. Saat ini, UI tidak menyertakan propertinya.

Untuk mendeklarasikan propertinya di UI, cukup tambahkan dekorator. Beri anotasi pada setiap properti yang diperlukan dengan @ApiProperty penghias. Anotasi properti opsional dengan @ApiPropertyOptional penghias.

Sebagai contoh:

// buat-demo.dto.ts
impor { ApiProperty, ApiPropertyOptional } dari '@nestjs/swagger';
eksporkelas BuatDemoDto {
@ApiProperty({
Tipe: Rangkaian,
 deskripsi: 'Ini adalah properti wajib',
 })
 Properti: rangkaian;
@ApiPropertyOptional({
Tipe: Rangkaian,
 deskripsi: 'Ini adalah properti opsional',
 })
 properti opsional: rangkaian;
}

Dekorator @ApiProperty dan @ApiPropertyOptional masing-masing menerima objek opsi. Objek itu menjelaskan properti yang mengikuti di bawah ini.

Perhatikan bahwa objek opsi menggunakan JavaScript, bukan TypeScript. Karenanya deklarasi tipe JavaScript (yaitu String, bukan string).

Memberi anotasi pada properti objek transfer data menambahkan contoh data yang diharapkan ke bagian Skema. Ini juga memperbarui rute HTTP terkait dengan contoh data yang diharapkan.

Langkah 5: Setel Tanggapan API

Di kelas pengontrol Anda, gunakan @ApiResponse dekorator untuk mendokumentasikan semua respons potensial untuk setiap rute HTTP. Untuk setiap titik akhir, dekorator @ApiResponse yang berbeda menjelaskan jenis respons yang diharapkan.

Kami telah menjelaskan tanggapan HTTP umum, jika Anda tidak terbiasa dengan artinya.

Dekorator @ApiResponse menerima objek opsional yang menjelaskan respons.

Tanggapan POST Umum

Untuk permintaan POST, kemungkinan tanggapannya meliputi:

  • ApiCreatedResponse, untuk 201 tanggapan yang berhasil dibuat.
  • ApiUnprocessableEnityResponse, untuk 422 respons entitas yang tidak dapat diproses yang gagal.
  • ApiForbiddenResponse, untuk 403 tanggapan terlarang.

Sebagai contoh:

// demo.controller.ts
@Pos()
@ApiCreatedResponse({ deskripsi: 'Berhasil Dibuat' })
@ApiUnprocessableEntityResponse({ deskripsi: 'Permintaan Buruk' })
@ApiForbiddenResponse({ deskripsi: 'Permintaan Tidak Sah' })
 membuat(@Tubuh() buatDemoDto: BuatDemoDto) {
kembaliini.demoService.create (createDemoDto);
 }

Tanggapan GET Umum

Untuk permintaan GET, kemungkinan tanggapannya meliputi:

  • ApiOkRespons, untuk 200 tanggapan ok.
  • ApiForbiddenResponse, untuk 403 tanggapan terlarang.
  • ApiNotFoundResponse, untuk 404 tanggapan tidak ditemukan.

Sebagai contoh:

// demo.controller.ts
@Mendapatkan()
@ApiOkResponse({ description: 'Sumber daya berhasil dikembalikan' })
@ApiForbiddenResponse({ deskripsi: 'Permintaan Tidak Sah' })
 Temukan semua() {
kembaliini.demoService.findAll();
 }
@Mendapatkan(':Indo')
@ApiOkResponse({ description: 'Sumber daya berhasil dikembalikan' })
@ApiForbiddenResponse({ deskripsi: 'Permintaan Tidak Sah' })
@ApiNotFoundResponse({ deskripsi: 'Sumber daya tidak ditemukan' })
 temukanSatu(@Param('aku melakukannya: rangkaian) {
kembaliini.demoService.findOne(+id);
 }

Tanggapan PATCH dan UPDATE Umum

Untuk permintaan PATCH dan UPDATE, kemungkinan tanggapannya meliputi:

  • ApiOkRespons, untuk 200 tanggapan ok.
  • ApiNotFoundResponse, untuk 404 tanggapan tidak ditemukan.
  • ApiUnprocessibleEntityResponse, untuk 422 respons entitas yang tidak dapat diproses yang gagal.
  • ApiForbiddenResponse, untuk 403 tanggapan terlarang.

Sebagai contoh:

// demo.controller.ts
@Patch(':Indo')
@ApiOkResponse({ description: 'Sumber daya berhasil diperbarui' })
@ApiNotFoundResponse({ deskripsi: 'Sumber daya tidak ditemukan' })
@ApiForbiddenResponse({ deskripsi: 'Permintaan Tidak Sah' })
@ApiUnprocessableEntityResponse({ deskripsi: 'Permintaan Buruk' })
 memperbarui(@Param('aku melakukannya: rangkaian, @Tubuh() updateDemoDto: UpdateDemoDto) {
kembaliini.demoService.update(+id, updateDemoDto);
 }

Tanggapan DELETE Umum

Untuk permintaan DELETE, kemungkinan tanggapan meliputi:

  • ApiOkRespons, untuk 200 tanggapan ok.
  • ApiForbiddenResponse, untuk 403 tanggapan terlarang.
  • ApiNotFoundResponse, untuk 404 tanggapan tidak ditemukan.

Sebagai contoh:

// demo.controller.ts
@Menghapus(':Indo')
@ApiOkResponse({ description: 'Sumber daya berhasil dikembalikan' })
@ApiForbiddenResponse({ deskripsi: 'Permintaan Tidak Sah' })
@ApiNotFoundResponse({ deskripsi: 'Sumber daya tidak ditemukan' })
 menghapus(@Param('aku melakukannya: rangkaian) {
kembaliini.demoService.remove(+id);
 }

Dekorator ini mengisi dokumentasi Anda dengan kemungkinan tanggapan. Anda dapat melihatnya menggunakan drop-down di samping setiap rute.

Melihat Dokumentasi Anda

Setelah penyiapan Anda selesai, Anda dapat melihat dokumentasi Anda di localhost:/api. Ini akan memunculkan dokumentasi API interaktif Anda.

Esensi dari dokumentasi Swagger API adalah deskripsi, tipe respons, dan definisi skema. Ini adalah hal-hal dasar yang diperlukan untuk membuat dokumentasi API yang baik.