Swagger เป็นเครื่องมืออันทรงพลังที่ช่วยให้นักพัฒนาสามารถสร้างและบันทึก RESTful API ของตนได้ ด้วย Swagger คุณสามารถสร้างเอกสารเชิงโต้ตอบ ทดสอบจุดสิ้นสุด และแม้แต่สร้างโค้ดไคลเอนต์ในภาษาต่างๆ มากมาย ในบล็อกนี้ เราจะพูดถึงวิธีใช้งาน Swagger กับ Node.js และ Express.js API ที่มีอยู่
ขั้นตอนที่ 1: ติดตั้ง Swagger ในการเริ่มต้น คุณจะต้องติดตั้งแพ็คเกจ Swagger คุณสามารถทำได้โดยใช้ npm โดยการรันคำสั่งต่อไปนี้:
npm install swagger-ui-express swagger-jsdoc
คำสั่งนี้จะติดตั้งแพ็คเกจที่จำเป็นเพื่อสร้างเอกสาร Swagger และให้บริการผ่าน Express.js
ขั้นตอนที่ 2: เพิ่ม Swagger ให้กับโปรเจ็กต์ของคุณ หลังจากติดตั้ง Swagger คุณจะต้องเพิ่มมันลงในโปรเจ็กต์ของคุณ สร้างไฟล์ใหม่ชื่อ swagger.js ในไดเร็กทอรีรากของโปรเจ็กต์ของคุณ และเพิ่มโค้ดต่อไปนี้:
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)); };
ในโค้ดนี้ เรากำลังสร้างอินสแตนซ์ Swagger ใหม่โดยส่งตัวเลือก API ของเรา นอกจากนี้ เรายังระบุเส้นทางไปยังเอกสาร API ของเราโดยใช้คุณสมบัติ apis สุดท้ายนี้ เรากำลังส่งออกฟังก์ชันที่เพิ่มมิดเดิลแวร์ Swagger ให้กับแอป Express.js ของเรา
ขั้นตอนที่ 3: เพิ่มความคิดเห็นของ Swagger ไปยังตำแหน่งข้อมูลของคุณ หลังจากที่เราได้เพิ่ม Swagger ในโครงการของเราแล้ว เราจำเป็นต้องเพิ่มความคิดเห็นไปยังตำแหน่งข้อมูลของเราเพื่อให้ Swagger สามารถสร้างเอกสารสำหรับพวกเขาได้ ต่อไปนี้เป็นตัวอย่างลักษณะของจุดสิ้นสุดที่มีการแสดงความคิดเห็น:
/** * @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 });
ในตัวอย่างนี้ เรากำลังใช้ความคิดเห็น Swagger เพื่อระบุวิธีการ HTTP (ในกรณีนี้คือ GET) ตำแหน่งข้อมูล (/users) คำอธิบายเกี่ยวกับสิ่งที่ตำแหน่งข้อมูลทำ และสคีมาการตอบสนอง
ขั้นตอนที่ 4: เรียกใช้แอปและดูเอกสารประกอบ เมื่อคุณเพิ่มความคิดเห็นของ Swagger ไปยังตำแหน่งข้อมูลของคุณแล้ว คุณสามารถเริ่มต้นแอปของคุณและไปที่ http://localhost:3000/api-docs เพื่อดูเอกสารประกอบของ Swagger
ในบล็อกนี้ เราได้กล่าวถึงพื้นฐานของการเพิ่ม Swagger ให้กับ Node.js และ Express.js API ที่มีอยู่ ด้วยการใช้ Swagger คุณสามารถสร้างเอกสารที่ครอบคลุมสำหรับ API ของคุณ และทำให้นักพัฒนาใช้ตำแหน่งข้อมูลของคุณได้ง่ายขึ้น ด้วยขั้นตอนเหล่านี้ คุณควรจะนำ Swagger ไปใช้ในโครงการของคุณเองได้ดี