วิธีใช้ Swagger สร้าง Node.js API

เอกสารประกอบ API ทำหน้าที่เป็นส่วนประกอบสำคัญในการพัฒนาซอฟต์แวร์ โดยให้ข้อมูลเชิงลึกแก่ผู้ใช้เกี่ยวกับวิธีการโต้ตอบกับ API และบริการต่างๆ ในคู่มือนี้ เราจะสำรวจการใช้ประโยชน์จาก Swagger ซึ่งเป็นเครื่องมือในการจัดทำเอกสาร API ที่สร้างขึ้นด้วย Node.js ทำให้สามารถสร้างเอกสารประกอบ API แบบโต้ตอบได้โดยอัตโนมัติและอำนวยความสะดวกในการทดสอบ API

นอกจากนี้ เราขอแนะนำ Apidog ในฐานะการผสานรวมที่มีประสิทธิภาพสำหรับการจัดการ API ที่ได้รับการปรับปรุง ซึ่งครอบคลุมการทดสอบในโปรโตคอลต่างๆ และการทำงานร่วมกันอย่างราบรื่น ด้วยคำแนะนำและข้อมูลเชิงลึกทีละขั้นตอน นักพัฒนาสามารถปรับปรุงการพัฒนา API และรับประกันความแข็งแกร่งและประสิทธิภาพในแอปพลิเคชันของตนได้

คู่มือฉบับสมบูรณ์เกี่ยวกับการจัดทำเอกสาร API ใน Swagger

ด้วย Swagger นักพัฒนาสามารถกำหนดจุดสิ้นสุด API พารามิเตอร์คำขอ รูปแบบการตอบสนอง และวิธีการตรวจสอบสิทธิ์โดยใช้รูปแบบ YAML หรือ JSON ที่เรียบง่ายและใช้งานง่าย รูปแบบเอกสารประกอบที่เป็นมาตรฐานนี้ไม่เพียงแต่ช่วยอำนวยความสะดวกในการสื่อสารระหว่างทีมพัฒนาเท่านั้น แต่ยังช่วยลดความซับซ้อนในการใช้งาน API สำหรับลูกค้าอีกด้วย

การตั้งค่าสภาพแวดล้อม Node.js

ก่อนที่เราจะเจาะลึกการสร้าง Node.js API ของเราด้วย Swagger มาตรวจสอบให้แน่ใจว่าสภาพแวดล้อมการพัฒนาของเราได้รับการตั้งค่าอย่างถูกต้อง ตรวจสอบให้แน่ใจว่าคุณได้ติดตั้ง Node.js บนเครื่องของคุณ คุณสามารถดาวน์โหลดและติดตั้ง Node.js ได้จากเว็บไซต์อย่างเป็นทางการ หรือใช้ตัวจัดการแพ็คเกจ เช่น npm หรือ yarn สำหรับการติดตั้ง

การติดตั้งเครื่องมือ Swagger

ในการเริ่มต้นใช้งาน Swagger เราจะต้องติดตั้งเครื่องมือ Swagger ที่จำเป็น ระบบนิเวศ Swagger มีเครื่องมือต่างๆ สำหรับขั้นตอนต่างๆ ของการพัฒนา API รวมถึง:

1. Swagger Editor: โปรแกรมแก้ไขบนเว็บสำหรับการออกแบบและทดสอบข้อมูลจำเพาะของ Swagger
2. Swagger UI: อินเทอร์เฟซที่เป็นมิตรต่อผู้ใช้สำหรับการแสดงภาพและโต้ตอบกับเอกสารประกอบ Swagger
3. Swagger Codegen: เครื่องมือสำหรับสร้างสตับเซิร์ฟเวอร์และไลบรารีไคลเอนต์ตามข้อมูลจำเพาะของ Swagger

คุณสามารถติดตั้งเครื่องมือเหล่านี้ทั่วโลกโดยใช้ npm หรือ yarn:

npm install -g swagger-cli swagger-ui-express

การออกแบบ API ของคุณด้วย Swagger

เมื่อตั้งค่าสภาพแวดล้อมการพัฒนาและติดตั้งเครื่องมือ Swagger แล้ว ตอนนี้เราสามารถเริ่มออกแบบ Node.js API ของเราโดยใช้ Swagger ขั้นตอนแรกคือการสร้างไฟล์ข้อมูลจำเพาะของ Swagger (โดยทั่วไปในรูปแบบ YAML หรือ JSON) ซึ่งอธิบาย จุดสิ้นสุด API พารามิเตอร์คำขอ รูปแบบการตอบสนอง และรายละเอียดอื่นๆ ที่เกี่ยวข้อง

นี่คือตัวอย่างพื้นฐานของข้อมูลจำเพาะของ Swagger สำหรับ Todo API อย่างง่าย:

openapi: 3.0.0
info:
  title: Todo API
  version: 1.0.0
  description: A simple Todo API
paths:
  /todos:
    get:
      summary: Get all todos
      responses:
        '200':
          description: A list of todos
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string
                    completed:
                      type: boolean
    post:
      summary: Create a new todo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: Buy groceries
                completed:
                  type: boolean
                  example: false
      responses:
        '201':
          description: Created

ในข้อมูลจำเพาะของ Swagger นี้:

• เรากำหนดชื่อ API เวอร์ชัน และคำอธิบายภายใต้ส่วน info
• เราระบุจุดสิ้นสุดสองจุด (/todos) หนึ่งจุดสำหรับการดึงข้อมูล todos ทั้งหมด (GET) และอีกจุดหนึ่งสำหรับการสร้าง todo ใหม่ (POST)
• แต่ละจุดสิ้นสุดมีบทสรุป เนื้อหาคำขอ (ถ้ามี) และรูปแบบการตอบสนอง

การทดสอบ API บน Swagger

เมื่อเราทำเอกสารประกอบ API ของเราเสร็จแล้ว เราควรจะสามารถดูเอกสารประกอบ Swagger และใช้เพื่อทดสอบ API ของเราได้ หากคุณทำตามขั้นตอนที่อธิบายไว้ก่อนหน้านี้ คุณควรเห็นอินเทอร์เฟซที่คล้ายกันตามที่อธิบายไว้ด้านล่าง เอกสารประกอบของเราจะให้บริการบนเส้นทาง /docs

เราจะใช้ UI เอกสาร Swagger เพื่อทำการร้องขอและสังเกตผลลัพธ์

การสร้างผู้ใช้:

การสร้างโพสต์:

ดังที่เราเห็นจากตัวอย่างข้างต้น เราสามารถใช้เอกสาร Swagger เพื่อทดสอบ API ของเรา ทำให้เราสามารถสร้าง อ่าน และแก้ไขข้อมูลในฐานข้อมูลได้ สิ่งนี้ช่วยให้ API เข้าใจและผสานรวมได้ง่ายขึ้น

ตามตัวอย่างเหล่านี้ เราสามารถทำการทดสอบวิธีการร้องขออื่นๆ ต่อไปได้ เช่น การใช้ PUT เพื่ออัปเดตผู้ใช้หรือโพสต์ การใช้ GET เพื่ออ่านผู้ใช้หรือโพสต์ และการใช้ DELETE เพื่อลบออกจากฐานข้อมูล

โดยสรุป เห็นได้ชัดว่าเอกสารประกอบ API มีบทบาทสำคัญในวงจรการพัฒนาซอฟต์แวร์ อำนวยความสะดวกในการทำงานร่วมกันและรับประกันประสบการณ์การใช้งานที่ราบรื่น ข้อดีของ Swagger เหนือสิ่งอื่นใด ได้แก่:

1. การซิงโครไนซ์เอกสารประกอบ API กับทั้งเซิร์ฟเวอร์และไคลเอนต์
2. การอำนวยความสะดวกในการสร้างและโต้ตอบกับเอกสารประกอบ REST API การใช้เฟรมเวิร์ก Swagger UI ช่วยให้ได้รับข้อมูลเชิงลึกที่ครอบคลุมเกี่ยวกับการตอบสนอง API ต่อพารามิเตอร์
3. การจัดเตรียมการตอบสนองในรูปแบบ JSON และ XML
4. ความสามารถรอบด้านสำหรับการใช้งานในเทคโนโลยีที่หลากหลาย

การจัดการเอกสารประกอบ API ด้วย Apidog

การจัดการ API ด้วย Swagger บางครั้งอาจยุ่งยากและขาดการทำงานร่วมกันระหว่างทีม ดังนั้นฉันขอแนะนำให้ใช้ Apidog แทน

Apidog เป็นเครื่องมือทดสอบ API ที่แข็งแกร่งกว่าเมื่อเทียบกับ Postman รองรับอินเทอร์เฟซการดีบักสำหรับโปรโตคอลต่างๆ เช่น HTTP(s), WebSocket, Socket, gRPC และผสานรวมกับปลั๊กอิน IDEA

เมื่อคุณพัฒนา API แล้ว คุณสามารถสร้างเอกสารประกอบ API ในหลายแพลตฟอร์มได้อย่างง่ายดายด้วยปลั๊กอิน IDEA ของ Apidog ทำให้การทดสอบและการบำรุงรักษาสะดวกมาก

การส่งออก Swagger เป็น JSON

ดังที่แสดงด้านล่าง เลือก "แปลงและบันทึกเป็น JSON" เพื่อส่งออกเอกสาร Swagger เป็นไฟล์ JSON

การนำเข้าไฟล์ Swagger ลงใน Apidog

เปิด Apidog สร้างโปรเจ็กต์ จากนั้นไปที่ "การตั้งค่าโปรเจ็กต์->นำเข้าข้อมูล->OpenAPI/Swagger->การนำเข้าไฟล์" และนำเข้าไฟล์ JSON ที่จัดรูปแบบ Swagger ที่คุณส่งออกก่อนหน้านี้

เมื่อนำเข้า จะมีการแสดงตัวอย่าง และคุณสามารถเลือกที่จะนำเข้าทั้งหมด หรือนำเข้า API แบบเลือกได้ หลังจากนำเข้าสำเร็จ คุณสามารถเลือกสภาพแวดล้อมเพื่อทดสอบ API ได้

ตรวจสอบลิงก์นี้เพื่อเรียนรู้เพิ่มเติม: https://apidog.com/help/importing-and-exporting-data/importing-data/importing-openapi-specification