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 ไปใช้ในโครงการของคุณเองได้ดี