Tutorial Membuat Dokumentasi Swagger

Swagger adalah salah satu alat paling populer untuk mendokumentasikan REST API. Dengan Swagger, pengembang dapat membuat dokumentasi interaktif sehingga pengembang atau pengguna lain dapat memahami dan menguji API langsung di browser. Dalam artikel ini, Anda akan mempelajari cara membuat dokumentasi Swagger untuk REST API Anda menggunakan Node.js dan Express.

Mempersiapkan lingkungan

Sebelum memulai, pastikan alat-alat berikut sudah terpasang:

Node.js dan npm: Untuk menjalankan server dan mengelola paket.

Express: Sebuah framework untuk Node.js untuk membuat REST API.

Swagger UI dan swagger-jsdoc: Pustaka untuk membuat dokumentasi API.

Untuk memulai proyek baru, jalankan perintah berikut:

bash id="npminitswagger"
npm init -y
npm install express swagger-ui-express swagger-jsdoc

swagger-ui-express: Menyediakan antarmuka web interaktif untuk dokumentasi.

swagger-jsdoc: Membaca komentar JSDoc dalam kode dan mengubahnya menjadi dokumentasi Swagger.

Buat server dasar

Buat file server.js dan tambahkan kode berikut:

javascript id="serverbasic"
const express = require('express');
const app = express();
konstanta PORT = 3000;

app.use(express.json());

aplikasi.get('/', (req, res) => {
res.send('Server API sedang berjalan!');
});

aplikasi mendengarkan(PORT, () => {
console.log(`Server berjalan di http://localhost:${PORT}`);
});

Kode ini membuat server sederhana yang siap diintegrasikan dengan Swagger.

Konfigurasi Swagger

Tambahkan konfigurasi Swagger ke file yang sama:

javascript id="swaggerconfig"
const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');

const swaggerDefinition = {
openapi: '3.0.0',
info: {
judul: 'Dokumentasi API REST',
versi: '1.0.0',
deskripsi: 'Contoh dokumentasi Swagger untuk API REST',
},
server: [
{ url: 'http://localhost:3000', description: 'Server Lokal' },
],
};

const options = {
Definisi kesombongan,
apis: ['./server.js'], // File yang berisi komentar JSDoc
};

const swaggerSpec = swaggerJSDoc(options);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Kode ini membuat endpoint /api-docs, yang memungkinkan akses ke dokumentasi interaktif di browser.

Tambahkan endpoint API

Contoh endpoint users:

javascript id = "titik akhir pengguna"
/**
* @swagger
* komponen:
* skema:
 *     Pengguna:
* tipe: objek
* properti:
 *         pengenal:
* tipe: bilangan bulat
* nama:
* tipe: string
*/

/**
* @swagger
* /pengguna:
 *   mendapatkan:
* Ringkasan: Mengambil semua pengguna
* tanggapan:
* 200:
* deskripsi: Daftar pengguna yang berhasil diambil
 *         isi:
* application/json:
* skema:
* tipe: array
* barang:
* $ref: '#/components/schemas/User'
*/
aplikasi.get('/users', (req, res) => {
const users = [
{ id: 1, nama: 'Ali' },
{ id: 2, nama: 'Budi' },
];
res.json(pengguna);
});

Komentar JSDoc menjelaskan endpoint dan model data User. Swagger secara otomatis menampilkan informasi ini di antarmuka web.

Memulai dan mengakses Swagger UI

Mulai server dengan:

bash id="runserver"
node server.js

Buka browser Anda dan kunjungi:

id="swaggerurl"
http://localhost:3000/api-docs

Anda sekarang sedang melihat dokumentasi interaktif yang berisi semua endpoint, model, dan kemampuan untuk menjalankan permintaan API secara langsung.

Tips untuk dokumentasi Swagger yang baik

Gunakan komentar JSDoc secara konsisten: Setiap endpoint harus dijelaskan dengan jelas.

Mendefinisikan skema: Gunakan components.schemas untuk membuat model data dapat digunakan kembali.

Tambahkan contoh: Tunjukkan contoh permintaan dan respons.

Pastikan dokumentasi selalu diperbarui: Perubahan pada API harus selalu didokumentasikan.

Gunakan OpenAPI 3.0: Versi ini menawarkan fitur modern dan dukungan yang lebih baik.

Kesimpulan

Swagger merupakan alat yang sangat membantu dalam membuat dokumentasi REST API yang interaktif, terstruktur, dan mudah dipahami. Dengan memanfaatkan Node.js, Express, serta pustaka seperti swagger-ui-express dan swagger-jsdoc, pengembang dapat membuat dokumentasi API secara otomatis langsung dari komentar JSDoc pada kode program.

Melalui Swagger UI, pengguna maupun pengembang lain dapat melihat informasi endpoint, model data, serta mencoba request API langsung melalui browser. Hal ini mempermudah proses pengembangan, pengujian, dan integrasi API dengan aplikasi lain. Selain itu, penggunaan OpenAPI 3.0 memberikan dukungan fitur modern yang membuat dokumentasi lebih lengkap dan fleksibel.

Agar dokumentasi tetap berkualitas, penting untuk menuliskan deskripsi endpoint secara jelas, mendefinisikan skema data dengan baik, serta selalu memperbarui dokumentasi ketika terjadi perubahan pada API. Dengan penerapan Swagger yang konsisten, REST API menjadi lebih mudah dipelajari, digunakan, dan dipelihara dalam pengembangan aplikasi modern.