Tutorial Dokumentasi Express API dengan Swagger UI dan JSDoc (Indonesia)

4 min readJun 18, 2024

Pengantar

Dokumentasi API adalah salah satu aspek paling krusial dalam pengembangan perangkat lunak modern. Dokumentasi yang baik tidak hanya membantu pengembang lain memahami cara kerja API, tetapi juga mempermudah proses pengembangan dan integrasi dengan sistem lain. Dalam artikel ini, kita akan membahas cara mendokumentasikan Express API menggunakan dua alat populer: Swagger UI dan JSDoc. Keduanya adalah alat yang sangat berguna untuk memastikan dokumentasi API Anda mudah dibaca dan digunakan.

Express.js adalah framework minimalis dan fleksibel untuk Node.js yang menyediakan berbagai fitur kuat untuk membangun aplikasi web dan API. Sementara itu, Swagger UI adalah alat yang memungkinkan Anda membuat dokumentasi API yang interaktif dan mudah diakses. JSDoc, di sisi lain, adalah alat untuk menghasilkan dokumentasi dari komentar dalam kode JavaScript Anda. Kombinasi kedua alat ini dapat memberikan dokumentasi API yang lengkap dan profesional.

Dalam artikel ini, kita akan membahas langkah-langkah untuk menginstal dan mengonfigurasi Express, Swagger UI, dan JSDoc, serta cara mengintegrasikan semuanya untuk membuat dokumentasi API yang optimal. Mari kita mulai!

Bagian 1: Mengenal Express dan Swagger UI

Express.js adalah framework untuk Node.js yang dirancang untuk membangun aplikasi web dan API dengan cepat dan efisien. Dengan arsitektur yang minimalis, Express menyediakan banyak fitur bawaan seperti routing dan middleware yang memudahkan pengembang untuk mengelola permintaan HTTP dan respons. Berikut adalah beberapa kelebihan menggunakan Express:

Mudah Dipelajari dan Digunakan: Dokumentasi yang baik dan komunitas yang besar membuat Express mudah untuk dipelajari, bahkan bagi pemula.
Performa Tinggi: Karena bersifat minimalis, Express tidak membebani aplikasi Anda dengan banyak fitur yang tidak diperlukan, sehingga performa tetap optimal.
Fleksibilitas: Express memungkinkan pengembang untuk menambahkan berbagai modul dan middleware sesuai kebutuhan, menjadikannya sangat fleksibel.

Swagger UI, di sisi lain, adalah alat yang membantu dalam membuat dokumentasi API yang interaktif. Dengan Swagger UI, Anda dapat melihat endpoint API, parameter, dan respons secara visual dan interaktif. Beberapa keuntungan menggunakan Swagger UI meliputi:

Dokumentasi Interaktif: Pengguna dapat mencoba endpoint API langsung dari halaman dokumentasi.
Meningkatkan Pemahaman: Tampilan visual membantu pengembang memahami bagaimana API bekerja dengan lebih mudah.
Standar Industri: Banyak perusahaan besar menggunakan Swagger UI untuk mendokumentasikan API mereka, menjadikannya standar industri yang diakui.

Bagian 2: Instalasi dan Konfigurasi Dasar

Sebelum kita mulai, pastikan Anda telah menginstal Node.js dan npm di sistem Anda. Jika belum, Anda dapat mengunduhnya dari situs resmi Node.js.

Langkah-langkah Instalasi Express:

mkdir express-api
cd express-api
npm init -y
npm install express

2. Membuat Server Express: Buat file index.js dan tambahkan kode berikut:

const express = require('express');
const app = express(); const port = 3000;
  app.get('/', (req, res) => {   res.send('Hello World!'); });
  app.listen(port, () => {   console.log(`Example app listening at http://localhost:${port}`);
 });

3. Instalasi Swagger UI:

npm install swagger-ui-express swagger-jsdoc

4. Konfigurasi Swagger UI: Tambahkan kode berikut ke file index.js:

const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerOptions = {   swaggerDefinition: {     openapi: '3.0.0',     info: {       title: 'Express API',       version: '1.0.0',       description: 'A simple Express API'     },   },   apis: ['./index.js'], };
const swaggerDocs = swaggerJsdoc(swaggerOptions); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

Sekarang, Anda dapat menjalankan server dan mengakses dokumentasi API di http://localhost:3000/api-docs.

Bagian 3: Penggunaan JSDoc untuk Dokumentasi Kode

JSDoc adalah alat yang digunakan untuk menulis komentar dalam kode JavaScript yang kemudian dapat diubah menjadi dokumentasi yang mudah dibaca. Untuk mulai menggunakan JSDoc, Anda perlu menginstalnya terlebih dahulu:

npm install jsdoc

Setelah instalasi, Anda bisa mulai menambahkan komentar JSDoc ke dalam kode Express Anda. Contoh sederhana adalah sebagai berikut:

/**
 * @swagger
 * /:
 *   get:
 *     summary: Home route
 *     description: Returns a simple greeting message.
 *     responses:
 *       200:
 *         description: A successful response
 */
app.get('/', (req, res) => {
  res.send('Hello World!');
});

Komentar di atas menggunakan format Swagger untuk mendokumentasikan endpoint API. Anda juga bisa menambahkan komentar JSDoc standar untuk fungsi-fungsi lainnya.

Bagian 4: Integrasi JSDoc dengan Swagger UI

Untuk mengonversi dokumentasi JSDoc menjadi Swagger UI, Anda bisa menggunakan plugin swagger-jsdoc. Langkah-langkahnya adalah sebagai berikut:

Pastikan Anda telah menambahkan komentar JSDoc ke dalam kode Anda.
Gunakan swagger-jsdoc untuk menghasilkan dokumentasi Swagger dari komentar JSDoc.

Contoh konfigurasi swagger-jsdoc sudah diberikan pada bagian sebelumnya. Dengan konfigurasi tersebut, komentar JSDoc yang Anda tulis akan secara otomatis diubah menjadi dokumentasi Swagger UI.

Bagian 5: Mengoptimalkan Dokumentasi API

Berikut beberapa tips untuk membuat dokumentasi API yang baik:

Jelas dan Ringkas: Pastikan setiap endpoint didokumentasikan dengan jelas, termasuk parameter, respons, dan contoh penggunaan.
Contoh yang Relevan: Sertakan contoh permintaan dan respons untuk membantu pengguna memahami cara kerja endpoint.
Terstruktur: Gunakan struktur yang konsisten untuk setiap endpoint sehingga dokumentasi mudah diikuti.
Diperbarui Secara Berkala: Selalu perbarui dokumentasi Anda setiap kali ada perubahan pada API.

Menggunakan fitur-fitur tambahan Swagger UI seperti pengelompokan endpoint dan filter juga dapat meningkatkan keterbacaan dan navigasi dokumentasi.

Kesimpulan

Dalam artikel ini, kita telah membahas cara mendokumentasikan Express API menggunakan Swagger UI dan JSDoc. Dokumentasi yang baik sangat penting untuk memudahkan pengembangan dan integrasi API. Dengan menggunakan Swagger UI dan JSDoc, Anda dapat membuat dokumentasi yang interaktif, jelas, dan mudah digunakan. Mulailah menggunakan tools ini dalam proyek Anda untuk memastikan API Anda terdokumentasi dengan baik dan profesional.

Jika Anda ingin melihat contoh kode yang lengkap, Anda dapat mengunjungi repositori GitHub saya di sini.

Referensi:

Express.js — Express Documentation
Node.js Documentation — Node.js Documentation
Swagger UI — Swagger UI Documentation