Swagger adalah alat canggih yang memungkinkan pengembang membuat dan mendokumentasikan RESTful API mereka. Dengan Swagger, Anda dapat membuat dokumentasi interaktif, menguji titik akhir, dan bahkan membuat kode klien dalam berbagai bahasa. Di blog ini, kita akan membahas cara mengimplementasikan Swagger dengan API Node.js dan Express.js yang sudah ada.
Langkah 1: Instal Swagger Untuk memulai, Anda perlu menginstal paket Swagger. Anda dapat melakukan ini menggunakan npm dengan menjalankan perintah berikut:
npm install swagger-ui-express swagger-jsdoc
Perintah ini akan menginstal paket yang diperlukan untuk menghasilkan dokumentasi Swagger dan menyajikannya melalui Express.js.
Langkah 2: Tambahkan Swagger ke proyek Anda Setelah menginstal Swagger, Anda perlu menambahkannya ke proyek Anda. Buat file baru bernama swagger.js di direktori root proyek Anda dan tambahkan kode berikut:
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'Your API Name',
version: '1.0.0',
description: 'A short description of your API',
},
},
apis: ['./routes/*.js'], // Path to the API docs
};
const specs = swaggerJsdoc(options);
module.exports = (app) => {
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
};
Dalam kode ini, kami membuat instance Swagger baru dengan meneruskan opsi API kami. Kami juga menentukan jalur ke dokumentasi API kami menggunakan properti apis. Terakhir, kami mengekspor fungsi yang menambahkan middleware Swagger ke aplikasi Express.js kami.
Langkah 3: Tambahkan komentar Swagger ke endpoint Anda Sekarang kita telah menambahkan Swagger ke proyek kita, kita perlu menambahkan komentar ke endpoint kita sehingga Swagger dapat menghasilkan dokumentasi untuk mereka. Berikut ini contoh tampilan titik akhir yang dikomentari:
/**
* @swagger
* /users:
* get:
* description: Returns a list of users
* responses:
* 200:
* description: A list of users
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*/
app.get('/users', (req, res) => {
// your code here
});
Dalam contoh ini, kami menggunakan komentar Swagger untuk menentukan metode HTTP (dalam hal ini, GET), titik akhir (/pengguna), deskripsi fungsi titik akhir, dan skema respons.
Langkah 4: Jalankan aplikasi Anda dan lihat dokumentasinya Setelah Anda menambahkan komentar Swagger ke endpoint Anda, Anda dapat memulai aplikasi Anda dan menavigasi ke http://localhost:3000/api-docs untuk melihat dokumentasi Swagger.
Di blog ini, kami telah membahas dasar-dasar menambahkan Swagger ke API Node.js dan Express.js yang sudah ada. Dengan menggunakan Swagger, Anda dapat menghasilkan dokumentasi komprehensif untuk API Anda dan memudahkan pengembang untuk menggunakan titik akhir Anda. Dengan langkah-langkah ini, Anda seharusnya sudah siap menerapkan Swagger dalam proyek Anda sendiri.
