Meskipun dokumentasi Postman sudah sangat bagus, di dunia industri ada sebuah standar yang lebih universal untuk mendeskripsikan API, yaitu OpenAPI Specification, dan alat paling populer untuk menampilkannya adalah Swagger.

Di pelajaran ini, kita akan belajar cara membuat dokumentasi yang canggih dan interaktif secara otomatis dari kode kita.

Bagian 1: Apa Itu Swagger dan OpenAPI?

Seringkali orang menggunakan istilah Swagger dan OpenAPI secara bergantian, tetapi sebenarnya ada sedikit perbedaan:

• OpenAPI Specification: Anggap ini sebagai sebuah aturan atau cetakan (blueprint). Ini adalah format standar (dalam bentuk file JSON atau YAML) untuk mendeskripsikan cara kerja sebuah RESTful API secara detail. Aturan ini tidak terikat pada bahasa pemrograman apa pun
• Swagger: Ini adalah kumpulan alat (tools) yang dibangun di sekitar OpenAPI Specification. Alat yang paling terkenal adalah Swagger UI, yang bisa mengambil file OpenAPI dan secara ajaib mengubahnya menjadi sebuah halaman web dokumentasi yang indah dan interaktif.

Mengapa ini menjadi standar industri? Karena format OpenAPI bisa dibaca baik oleh manusia maupun oleh mesin. Ini memungkinkan berbagai tools untuk secara otomatis membuat dokumentasi, melakukan pengujian, atau bahkan membuat kode client dalam berbagai bahasa (Java, Python, dll.) hanya dari satu file definisi.

Bagian 2: Menyiapkan Proyek Express.js untuk Swagger

Cara paling keren menggunakan Swagger adalah dengan membiarkannya membaca komentar di kode kita dan membuat dokumentasi secara otomatis. Mari kita siapkan.

1. Instalasi Library yang Dibutuhkan

Buka terminal di proyekmu dan jalankan perintah ini untuk menginstal dua library baru:

npm install swagger-jsdoc swagger-ui-express

• swagger-jsdoc: Library untuk membaca komentar di kode kita dan mengubahnya menjadi spesifikasi OpenAPI.
• swagger-ui-express: Library untuk menampilkan spesifikasi tersebut menggunakan antarmuka Swagger UI di dalam aplikasi Express kita.

2. Tambahkan Komentar Khusus di File Router

Buka file router-mu di src/routes/student.route.js. Sekarang, tambahkan blok komentar khusus di atas setiap route yang sudah ada.

// src/routes/student.route.js

const express = require('express');
const router = express.Router();
const studentController = require('../controllers/student.controller.js');

/**
 * @swagger
 * /students:
 * get:
 * summary: Mengambil semua data siswa
 * description: Endpoint ini digunakan untuk mengambil seluruh daftar siswa yang ada di database.
 * responses:
 * '200':
 * description: Daftar siswa berhasil ditampilkan.
 */
router.get('/', studentController.getAllStudents);

/**
 * @swagger
 * /students:
 * post:
 * summary: Menambahkan siswa baru
 * description: Endpoint untuk menambahkan data siswa baru ke dalam database.
 * requestBody:
 * required: true
 * content:
 * application/json:
 * schema:
 * type: object
 * properties:
 * nama:
 * type: string
 * example: "Gita"
 * responses:
 * '200':
 * description: Siswa berhasil ditambahkan.
 */
router.post('/', studentController.createNewStudent);

// (Tambahkan komentar serupa untuk PUT dan DELETE)

module.exports = router;

3. Konfigurasi Swagger di index.js

Terakhir, buka file src/index.js dan tambahkan kode untuk menyajikan dokumentasi Swagger.

// src/index.js

const express = require('express');
// Tambahkan 3 baris di bawah ini
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
const studentRouter = require('./routes/student.route.js');

const app = express();
const port = 3000;

// Opsi untuk swagger-jsdoc
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API Data Siswa Bootcamp',
      version: '1.0.0',
      description: 'Dokumentasi API sederhana untuk mengelola data siswa',
    },
  },
  // Path ke file yang berisi definisi API (route kita)
  apis: ['./src/routes/*.js'],
};

const swaggerSpec = swaggerJsdoc(options);

app.use(express.json());

// Sajikan dokumentasi Swagger di endpoint /api-docs
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

app.use('/students', studentRouter);

// ... (kode error handler dan app.listen)
app.listen(port, function () {
  console.log(`Server berjalan di http://localhost:${port}`);
});

Bagian 3: Melihat Keajaiban Swagger UI

Sekarang bagian yang paling menyenangkan.

1. Jalankan ulang servermu (node src/index.js).
2. Buka Browser: Buka browser internet-mu (Chrome, Firefox, dll).
3. Akses URL Dokumentasi: Kunjungi alamat http://localhost:3000/api-docs.

Kamu akan disambut oleh sebuah halaman dokumentasi yang sangat profesional.

Coba Interaksinya!

• Klik pada salah satu endpoint, misalnya GET /students.
• Kamu akan melihat deskripsi yang sudah kamu tulis di komentar.
• Klik tombol “Try it out”.
• Lalu klik tombol biru “Execute”.

Swagger UI akan secara otomatis mengirimkan request ke API-mu dan menampilkan hasilnya langsung di halaman tersebut. Ini adalah cara yang sangat ampuh untuk mendemonstrasikan dan menguji API tanpa perlu membuka Postman.