ทำไม Swagger Docs และ Postman Collections ของคุณถึงคลาดเคลื่อน (และวิธีแก้ไข)

ความเหลื่อมล้ำระหว่าง Swagger และ Postman ไม่ใช่ความล้มเหลวของกระบวนการ เป็นสิ่งที่เกิดขึ้นเมื่อคุณจัดเก็บสัญญาเดียวกันในสองที่โดยไม่มีกลไกใด ๆ ที่จะทำให้ข้อมูลตรงกัน คุณเขียนสเปค OpenAPI, ชี้ Swagger UI ไปที่สเปคเพื่อทำเอกสาร, จากนั้นส่งออก Postman collection เพื่อใช้ทดสอบ หนึ่งสัปดาห์ต่อมา มีคนเปลี่ยนเอนด์พอยต์ใน collection โดยไม่ได้แก้ไขไฟล์ YAML และตอนนี้เอกสารและการทดสอบของคุณอธิบายถึง API ที่แตกต่างกัน บทความนี้จะอธิบายว่าทำไมผลลัพธ์เช่นนั้นจึงรับประกันได้ในเชิงโครงสร้าง และรูปแบบแหล่งข้อมูลเดียวที่เชื่อถือได้ (single-source-of-truth) เป็นอย่างไรในทางปฏิบัติ สำหรับขั้นตอนการสร้างการทดสอบจากสเปค ดูได้จาก วิธีปฏิบัติที่มีอยู่แล้วเกี่ยวกับการสร้างการทดสอบ OpenAPI

ทำไมไฟล์สองไฟล์จึงมักจะคลาดเคลื่อนออกจากกันเสมอ

คุณดูแลไฟล์ openapi.yaml ในรีโพของคุณ คุณยังเก็บ Postman collection ไว้ด้วย วัตถุทั้งสองนี้อธิบายสัญญา API เดียวกัน แต่ถูกจัดเก็บแยกกัน แก้ไขโดยบุคคลต่างกัน และอัปเดตตามตารางเวลาที่แตกต่างกัน ไม่มีเครื่องมือใด ๆ ที่บังคับใช้ความสอดคล้องกันระหว่างทั้งสอง

ลองพิจารณาสถานการณ์จริง ทีมแบ็กเอนด์ของคุณปล่อยเอนด์พอยต์ใหม่ POST /payments/refund พร้อมฟิลด์ reason ที่จำเป็น มีคนเพิ่มเอนด์พอยต์นี้ลงใน Postman collection เพราะเป็นที่ที่พวกเขารันการทดสอบ การอัปเดต openapi.yaml ถูกจัดอยู่ในรายการค้างของสปรินต์ สามวันต่อมา นักพัฒนาฟรอนต์เอนด์อ่านเอกสาร Swagger เรียกเอนด์พอยต์โดยไม่มี reason และได้รับรหัส 400 ที่พวกเขาไม่สามารถอธิบายได้จากเอกสารเพียงอย่างเดียว

สาเหตุหลักไม่ใช่ความประมาทเลินเล่อ แต่เป็นการไม่มีการผูกมัดใด ๆ ระหว่างสิ่งประดิษฐ์ทั้งสอง ไม่มีเครื่องมือใดที่รู้ว่าอีกเครื่องมือหนึ่งมีอยู่

ตารางข้างบนแสดงปัญหาได้อย่างชัดเจน สามแถว, เจ้าของที่อัปเดตสามคน, ไม่มีการตรวจสอบข้ามกันเลย แม้ว่าคุณจะรัน linter อย่าง Spectral กับไฟล์ YAML ของคุณ มันก็ตรวจจับข้อผิดพลาดของสคีมา ไม่ใช่ช่องว่างระหว่าง YAML กับ collection ที่อยู่ในเครื่องมืออื่นโดยสิ้นเชิง

ปัญหาสามชุดข้อมูล

ทีมที่ใช้แพลตฟอร์มเอกสารแยกต่างหาก เช่น Stoplight ยิ่งเพิ่มความซับซ้อนให้กับปัญหา ตอนนี้คุณมีสำเนาของสัญญาอยู่สามชุด:

1. ไฟล์ openapi.yaml ที่คอมมิตเข้า Git
2. Postman collection ที่ส่งออกและแชร์เป็น workspace
3. เอกสารที่แสดงผลใน Stoplight (หรือ Swagger UI, หรือ wiki)

สำเนาแต่ละชุดสามารถคลาดเคลื่อนออกจากกันได้โดยอิสระ OpenAPI Specification เองก็ไม่มีกลไกการบังคับใช้ในขณะรันไทม์ มันเป็นรูปแบบการอธิบาย ไม่ใช่โปรโตคอลการซิงโครไนซ์ คุณสามารถอธิบาย API ใดก็ได้ที่คุณต้องการใน YAML ไม่มีอะไรหยุด Postman collection ของคุณจากการทำสิ่งที่แตกต่างออกไปได้

นี่คือแรงกดดันเดียวกันกับที่ทีมงานใน World Economic Forum พบเจอเมื่อพวกเขารักษา OpenAPI specs ใน GitHub ควบคู่ไปกับ Postman collections ที่แยกต่างหาก และเว็บไซต์เอกสารแยกต่างหาก สามสถานที่สำหรับสัญญาเดียวกันหมายถึงจุดล้มเหลวสามจุดและวงจรการซิงโครไนซ์ด้วยตนเองสามวงจร เมื่อคุณเพิ่มขนาดทีมและบริการหลายอย่าง ต้นทุนการบำรุงรักษาก็จะเพิ่มขึ้นแบบไม่เชิงเส้น

ความเหลื่อมล้ำทำลายการทดสอบอย่างเงียบ ๆ ได้อย่างไร

ส่วนที่ร้ายกาจของความเหลื่อมล้ำระหว่าง Swagger และ Postman คือการทดสอบยังคงผ่านได้แม้ว่าจะผิดพลาด หาก Postman collection ของคุณยังคงส่งสคีมาของ request body แบบเก่า และแบ็กเอนด์ทดสอบของคุณยอมรับทั้งสคีมาเก่าและใหม่ในช่วงระยะเวลาการย้ายข้อมูล การรันการทดสอบที่ผ่านก็ไม่ได้บอกอะไรคุณเลยว่าสเปคปัจจุบันนั้นได้รับการครอบคลุมหรือไม่

นี่คือตัวอย่างส่วนของ YAML ที่แสดงการเปลี่ยนแปลงสเปคซึ่งอาจเล็ดลอดผ่าน Postman collection ที่ล้าสมัยไปได้:

# openapi.yaml - สเปคที่อัปเดต (v2)
paths:
  /payments/refund:
    post:
      summary: Initiate a refund
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_id
                - reason          # ฟิลด์ใหม่ที่จำเป็นเพิ่มเข้ามาใน v2
              properties:
                transaction_id:
                  type: string
                  example: "txn_8x9Ka21"
                reason:
                  type: string
                  enum: [duplicate, fraudulent, requested_by_customer]
                  example: "requested_by_customer"
      responses:
        '200':
          description: Refund initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  refund_id:
                    type: string
                  status:
                    type: string

Postman collection ที่ถูกตรึงไว้ที่เวอร์ชัน 1 จะส่งเพียง transaction_id เท่านั้น หากทีมแบ็กเอนด์เพิ่มค่าเริ่มต้นแบบผ่อนปรนสำหรับ reason ระหว่างการเปิดตัว การทดสอบ Postman แบบเก่าก็จะผ่าน สเปคระบุว่า reason เป็นสิ่งที่จำเป็น แต่การทดสอบไม่เคยส่งค่านี้ ไม่มีใครสังเกตเห็นจนกว่าการทำงานร่วมกันของฟรอนต์เอนด์จะพังใน staging

การรัน OpenAPI validator ที่ถูกต้องกับไฟล์ YAML ของคุณจะตรวจจับความไม่สอดคล้องกันของสคีมาภายในสเปคได้ แต่ไม่สามารถตรวจจับช่องว่างระหว่างสเปคกับสิ่งที่ Postman collection ของคุณส่งจริงได้

การทดสอบแบบ OpenAPI-driven หมายความว่าอย่างไร

การทดสอบแบบ OpenAPI-driven หมายความว่าสเปคเป็นแหล่งข้อมูลที่เชื่อถือได้ การทดสอบถูกสร้างขึ้นจากสเปค ไม่ใช่เขียนควบคู่ไปกับสเปค เมื่อสเปคเปลี่ยน การทดสอบก็จะสะท้อนการเปลี่ยนแปลงนั้นโดยอัตโนมัติ เพราะใช้แหล่งข้อมูลเดียวกัน

สิ่งนี้แตกต่างจากการ “นำเข้า Swagger เข้าสู่ Postman” การนำเข้าเป็นการคัดลอกครั้งเดียว คุณกดนำเข้า ได้ collection มา และวัตถุทั้งสองก็จะกลายเป็นอิสระต่อกันทันทีอีกครั้ง การเปลี่ยนแปลงสเปคครั้งต่อไปต้องมีการนำเข้าด้วยตนเองอีกครั้ง หรือแก้ไข collection ด้วยตนเองอีกครั้ง คุณยังไม่ได้แก้ปัญหาความเหลื่อมล้ำ; คุณเพียงแค่รีเซ็ตมันให้เป็นศูนย์

การดำเนินการแบบ spec-first ที่แท้จริงมีลักษณะดังนี้:

1. ไฟล์ OpenAPI อยู่ใน Git ในฐานะสัญญาหลักที่เชื่อถือได้
2. เครื่องมือจะอ่านไฟล์นั้นและสร้าง mocks, เอกสาร และกรณีทดสอบจากไฟล์นั้น
3. เมื่อไฟล์มีการเปลี่ยนแปลง (ผ่านการรีวิว PR) mocks และกรณีทดสอบก็จะอัปเดต
4. ไม่มี collection แยกต่างหากที่ต้องคอยซิงโครไนซ์

โมเดล การพัฒนา API แบบ spec-first อธิบายปรัชญาการทำงานที่กว้างขึ้น บทความนี้มุ่งเน้นไปที่ปัญหาเฉพาะของความเหลื่อมล้ำระหว่างเอกสารและการทดสอบ

Apidog ในฐานะเลเยอร์การดำเนินการเหนือสเปคเดียว

โมเดลของ Apidog ถือว่า Git เป็นแหล่งข้อมูลที่เชื่อถือได้ และ Apidog เป็นเลเยอร์การดำเนินการที่อยู่เหนือ Git คุณคอมมิตไฟล์ openapi.yaml ของคุณ Apidog จะอ่านไฟล์นั้นและสร้างผลลัพธ์สามอย่างจากไฟล์เดียว ได้แก่ เอกสารแบบโต้ตอบ, เซิร์ฟเวอร์ mock และชุดการทดสอบ

Apidog’s Spec-First Mode (ปัจจุบันอยู่ในรุ่นเบต้า) ถูกออกแบบมาเพื่อเวิร์กโฟลว์นี้โดยเฉพาะ คุณชี้ไปที่ไฟล์ OpenAPI ของคุณ และแพลตฟอร์มจะสร้างผลลัพธ์ทั้งสามอย่างโดยที่คุณไม่ต้องดูแล collection แยกต่างหาก เมื่อคุณอัปเดตไฟล์ YAML และพุช ผลลัพธ์ปลายทางก็จะอัปเดต

ผลลัพธ์ที่ใช้งานได้จริงคือจะไม่มี Postman collection ที่จะคลาดเคลื่อนได้ มีไฟล์เดียวเท่านั้น เวิร์กโฟลว์ sync-openapi-spec อธิบายถึงวิธีการที่ทีมคอมมิตสเปคไปยัง GitHub และทำให้ Apidog สอดคล้องกัน

สำหรับทีมที่มาจากเวิร์กโฟลว์ที่เน้น Postman ควรตรวจสอบในการทดลองใช้ว่า Apidog จัดการสถานการณ์การทดสอบที่ขับเคลื่อนด้วยข้อมูล (data-driven test scenarios) ที่มีสคีมาที่ซับซ้อนเฉพาะของคุณอย่างไร และสิทธิ์การมองเห็นรายงานตรงกับโมเดลการเข้าถึงขององค์กรของคุณหรือไม่ คำถามเหล่านี้เป็นคำถามที่ดีสำหรับการพิสูจน์แนวคิด (POC) ก่อนที่คุณจะย้ายชุดการผลิต

การทำ API mocking ก็เป็นส่วนสำคัญของภาพรวมเช่นกัน เมื่อ mock ถูกสร้างขึ้นจากสเปคเดียวกับการทดสอบ นักพัฒนาฟรอนต์เอนด์ที่เรียกใช้ mock จะได้รับผลตอบรับที่สอดคล้องกับสิ่งที่การทดสอบตรวจสอบ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับบทบาทของการ mocking โปรดดูที่ กรณีการใช้งาน API mocking

เส้นทางการย้ายข้อมูลมีลักษณะอย่างไร

หากคุณกำลังเปลี่ยนจากการตั้งค่า Swagger + Postman การย้ายข้อมูลไม่ใช่การแทนที่แบบครั้งเดียวทั้งหมด ลำดับที่สมเหตุสมผลคือ:

1. ตรวจสอบไฟล์ openapi.yaml ปัจจุบันของคุณเทียบกับ Postman collection ของคุณ ค้นหาเอนด์พอยต์ทุกรายการใน collection ที่ไม่ได้อยู่ในสเปค และเอนด์พอยต์ทุกรายการในสเปคที่ collection ไม่ครอบคลุม
2. ปรับปรุงสเปคให้สอดคล้องกัน ควรจะอธิบายถึง API ปัจจุบันที่เป็นจริง ไม่ใช่ API ที่มีอยู่เมื่อคุณเขียน YAML ครั้งแรก
3. นำเข้าสเปคเข้าสู่ Apidog ให้ Apidog สร้างชุดการทดสอบเบื้องต้นจากโครงสร้างสเปค
4. เลิกใช้ Postman collection อย่างค่อยเป็นค่อยไป รันทั้งสองอย่างพร้อมกันเป็นเวลาหนึ่งสปรินต์เพื่อเปรียบเทียบผลลัพธ์
5. เก็บถาวร collection ให้ Git เป็นแหล่งข้อมูลที่เชื่อถือได้ Apidog จัดการการดำเนินการ

ขั้นตอนที่ 1 มักจะเป็นขั้นตอนที่อึดอัดที่สุด เพราะมันแสดงให้เห็นว่าสิ่งประดิษฐ์ทั้งสองมีความเหลื่อมล้ำกันมากเพียงใด ทีมที่ปล่อยให้ความเหลื่อมล้ำสะสมมาเป็นเวลาหกเดือนมักจะพบช่องว่างในการครอบคลุมเอนด์พอยต์ 20 ถึง 40 เปอร์เซ็นต์

สำหรับการสร้างชุดการทดสอบเบื้องต้นจากสเปคของคุณ วิธีปฏิบัติเฉพาะที่ การสร้างชุดการทดสอบจาก OpenAPI specs ครอบคลุมกลไกโดยละเอียด บทความนี้จงใจที่จะหยุดก่อนขั้นตอนนี้; บทแนะนำการสร้างจะดีกว่าเมื่อคุณมีสเปคที่สะอาดแล้ว

เปรียบเทียบ: การบำรุงรักษาสองแหล่งข้อมูล vs. สเปคเป็นแหล่งข้อมูลหลัก

คอลัมน์การบำรุงรักษาสองแหล่งข้อมูลไม่ใช่ความล้มเหลวของ Postman ในฐานะเครื่องมือ Postman มีความโดดเด่นในการทดสอบแบบ collection-based และมีระบบนิเวศขนาดใหญ่ ปัญหาคือรูปแบบเวิร์กโฟลว์ของการปฏิบัติต่อ collection ในฐานะสัญญาคู่ขนาน แทนที่จะเป็นสิ่งประดิษฐ์ที่ได้มา

คำถามที่พบบ่อย

ทำไมการนำเข้า Swagger เข้าสู่ Postman จึงไม่สามารถแก้ปัญหาความเหลื่อมล้ำได้?

การนำเข้าสร้างสำเนา ณ จุดเวลาหนึ่ง หลังจากการนำเข้า วัตถุทั้งสองจะเป็นอิสระต่อกัน การเปลี่ยนแปลงถัดไปใน openapi.yaml ของคุณจะไม่ส่งผลไปยัง collection โดยอัตโนมัติ คุณจะต้องนำเข้าใหม่หรือแก้ไข collection ด้วยตนเองทุกครั้งที่สเปคมีการเปลี่ยนแปลง ซึ่งจะนำคุณกลับไปสู่ปัญหาการบำรุงรักษาสองแหล่งข้อมูล

ฉันยังคงใช้ Postman สำหรับการทดสอบเชิงสำรวจได้หรือไม่ในขณะที่ใช้โมเดล spec-first?

ได้ โมเดล spec-first ไม่ได้ห้ามการทดสอบเฉพาะกิจ คุณสามารถใช้ Postman สำหรับการเรียกใช้เพื่อสำรวจแบบครั้งคราวได้ ในขณะที่ย้ายชุดการทดสอบการถดถอยแบบอัตโนมัติของคุณไปยังตัวรันที่ขับเคลื่อนด้วยสเปค หัวใจสำคัญคือการไม่คอมมิต collection สำหรับการสำรวจในฐานะแหล่งข้อมูลที่เชื่อถือได้สำหรับการตรวจสอบสัญญา

ฉันจะรู้ได้อย่างไรว่าสเปคของฉันคลาดเคลื่อนจากการใช้งาน API จริงเมื่อใด?

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

Apidog สามารถมาแทนที่ Postman ได้ทั้งหมดหรือไม่?

ขึ้นอยู่กับเวิร์กโฟลว์ของทีมคุณ Apidog จัดการการออกแบบ, mocking, การทดสอบ และเอกสารจาก workspace เดียว สำหรับทีมที่ใช้ Postman เป็นหลักสำหรับการทดสอบสัญญาและชุดการถดถอย Apidog ก็ครอบคลุมส่วนนั้น หากทีมของคุณใช้ Postman’s collection runner ใน CI หรือมีสคริปต์ collection ที่ครอบคลุม, การทดสอบด้วย Postman ยังคงเป็นทางเลือกหนึ่งควบคู่ไปกับเวิร์กโฟลว์การออกแบบแบบ spec-first ควรประเมินทั้งสองอย่างในการทดลองใช้สปรินต์

จะเกิดอะไรขึ้นหากไฟล์ openapi.yaml ของฉันล้าสมัยไปแล้ว?

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

สรุป

เอกสาร Swagger และ Postman collections มีความเหลื่อมล้ำกันเนื่องจากเป็นสิ่งประดิษฐ์สองชิ้นที่แยกจากกันและไม่มีการผูกมัดระหว่างกัน นั่นเป็นคุณสมบัติเชิงโครงสร้างของเวิร์กโฟลว์การบำรุงรักษาสองแหล่งข้อมูล ไม่ใช่ปัญหาด้านระเบียบวินัยของทีม วิธีแก้ไขคือการกำจัดสิ่งประดิษฐ์ชิ้นที่สองออกไป: ใช้ไฟล์ OpenAPI ไฟล์เดียวใน Git พร้อมเครื่องมือที่สร้าง mocks, การทดสอบ และเอกสารจากไฟล์นั้น แทนที่จะปล่อยให้แต่ละส่วนมีอยู่แยกกัน

ดาวน์โหลด Apidog และนำเข้าสเปค OpenAPI ที่มีอยู่ของคุณ คุณจะเห็นได้ในการทำงานเพียงครั้งเดียวว่าไฟล์เดียวสามารถแทนที่ทั้งเอกสาร Swagger และ Postman collection ของคุณได้อย่างไร โดยมี mocks, การทดสอบ และเอกสารทั้งหมดอ่านจากแหล่งข้อมูลเดียวกัน หากคุณกำลังประเมิน Spec-First Mode (ปัจจุบันอยู่ในรุ่นเบต้า) โปรดตรวจสอบ หน้า Apidog Spec-First Mode เพื่อดูขอบเขตคุณสมบัติปัจจุบันและรายละเอียดการเข้าถึง