สร้าง OpenAPI Specs จาก Requests ที่มีอยู่

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

คู่มือนี้จะอธิบายว่าทำไมวิธีการนี้จึงได้ผล เครื่องมือใดบ้างที่สามารถช่วยได้ และวิธีที่คุณสามารถเปลี่ยนคำขอจริงให้เป็น OpenAPI spec ที่สะอาดและนำกลับมาใช้ใหม่ได้ ซึ่งทีมของคุณสามารถไว้วางใจได้

วิธีที่ 1: แนวทาง "Code-First"

วิธีนี้ใช้ได้ผลหากคุณสามารถเพิ่ม annotations หรือไลบรารีลงในโค้ดแอปพลิเคชันแบ็กเอนด์ของคุณได้โดยตรง

ทำงานอย่างไร?

คุณติดตั้งไลบรารีในเฟรมเวิร์กเว็บของคุณ ซึ่งจะตรวจสอบโค้ด เส้นทาง, คอนโทรลเลอร์ และโมเดลของคุณ จากนั้นสร้าง OpenAPI specification ได้ทันที

ไลบรารียอดนิยม:

• Node.js (Express): swagger-jsdoc หรือ tsoa (TypeScript OpenAPI)
• Python (FastAPI/Flask): FastAPI มีสิ่งนี้ในตัว! Flask สามารถใช้ flasgger หรือ flask-restx ได้
• Java (Spring Boot): springdoc-openapi
• .NET: Swashbuckle

ตัวอย่างกับ FastAPI (Python):

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    """
    Create a new item in the database.
    - **name**: The item's name
    - **price**: The item's price in USD
    """
    return item

# โค้ดนี้จะสร้าง OpenAPI spec ฉบับเต็มโดยอัตโนมัติที่ /docs หรือ /openapi.json

ข้อดี:

• แม่นยำเสมอ: spec ได้มาจากโค้ดที่ทำงานอยู่โดยตรง
• บำรุงรักษาน้อย: อัปเดตโค้ด แล้ว spec จะอัปเดตโดยอัตโนมัติ

ข้อเสีย:

• ต้องเข้าถึงโค้ด: คุณไม่สามารถใช้วิธีนี้กับ API ของบุคคลที่สามหรือ API เก่าที่คุณไม่ได้ควบคุมได้
• อาจทำให้โค้ดรก: การใช้ OpenAPI annotations จำนวนมากอาจทำให้ตรรกะทางธุรกิจอ่านยากขึ้น

วิธีที่ 2: แนวทาง "การวิเคราะห์ทราฟฟิก"

นี่เป็นแนวทาง "จากภายนอกสู่ภายใน" ที่ชาญฉลาด คุณ บันทึกทราฟฟิก HTTP จริง ระหว่างไคลเอนต์และ API ของคุณ จากนั้นวิเคราะห์เพื่ออนุมาน specification

ทำงานอย่างไร?

คุณใช้เครื่องมือที่ทำหน้าที่เป็นพร็อกซีหรือ network sniffer ทราฟฟิก API ทั้งหมดจะถูกส่งผ่านเครื่องมือนี้ เครื่องมือจะวิเคราะห์คำขอและการตอบกลับ (URL, เมธอด, เฮดเดอร์, บอดี้) และสร้างโมเดลของ API ของคุณ

เครื่องมือยอดนิยม:

• Akita Software: สังเกตทราฟฟิก API โดยอัตโนมัติเพื่อสร้างและตรวจสอบ specs
• การสร้างไฟล์ HAR: คุณสามารถใช้ Developer Tools ของเบราว์เซอร์ (แท็บ Network) เพื่อบันทึกเซสชันกับ API ของคุณและส่งออกเป็นไฟล์ HAR (HTTP Archive) เครื่องมือบางอย่างสามารถแปลงไฟล์นี้เป็น OpenAPI ได้

กระบวนการ:

1. กำหนดค่าแอปหรือไคลเอนต์ของคุณเพื่อส่งทราฟฟิกผ่านเครื่องมือพร็อกซี
2. ดำเนินการเวิร์กโฟลว์ API หลักของคุณ (เข้าสู่ระบบ, สร้างข้อมูล, ดึงข้อมูล ฯลฯ)
3. เครื่องมือจะสังเกตแบบแผนและสร้าง OpenAPI spec เบื้องต้น

ข้อดี:

• เหมาะสำหรับ API เก่า/black-box: ทำงานได้โดยไม่ต้องเปลี่ยนแปลงโค้ดใดๆ หรือความร่วมมือจากเซิร์ฟเวอร์
• อิงตามการใช้งานจริง: บันทึกเอนด์พอยต์และรูปแบบข้อมูลที่ใช้งานจริง

ข้อเสีย:

• อาจไม่สมบูรณ์: สร้าง specs เฉพาะสำหรับเอนด์พอยต์ที่คุณเรียกใช้ระหว่างการบันทึกเท่านั้น
• อาจพลาดรายละเอียดปลีกย่อย: อาจไม่สามารถอนุมานข้อจำกัด, ฟิลด์ที่ไม่บังคับ หรือการตอบสนองข้อผิดพลาดทั้งหมดได้อย่างถูกต้อง
• ค่าใช้จ่ายในการตั้งค่า: ต้องมีการดักจับทราฟฟิกเครือข่าย ซึ่งอาจเป็นเรื่องยุ่งยากในบางสภาพแวดล้อม

วิธีที่ 3: แนวทาง "การรวบรวมคำขอ"

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

นี่คือจุดที่พลังของ Apidog โดดเด่น มันถูกสร้างมาเพื่อเวิร์กโฟลว์นี้

ทำงานอย่างไรกับ Apidog?

1. ส่งคำขอตามปกติ: ไม่ต้องเปลี่ยนเวิร์กโฟลว์ของคุณ ใช้ Apidog เพื่อทดสอบและดีบักเอนด์พอยต์ API ที่มีอยู่ของคุณ เมื่อคุณส่งคำขอ GET, POST, PUT และ DELETE, Apidog จะบันทึกรายละเอียดทั้งหมด

2. ให้ Apidog สร้างโมเดล: เบื้องหลังการทำงานของคุณ Apidog จะเริ่มทำความเข้าใจโครงสร้าง API ของคุณ มันจะเห็นเอนด์พอยต์, พารามิเตอร์, บอดี้คำขอ และสกีมาการตอบกลับ

3. จัดระเบียบเป็นเอกสาร: Apidog สามารถเปลี่ยนคำขอให้เป็นเอกสาร API ได้แบบเรียลไทม์ คำขอชั่วคราวของคุณจะกลายเป็นหน้าเอกสาร API ที่มีโครงสร้างและนำทางได้ภายในเครื่องมือ คุณสามารถเพิ่มคำอธิบาย, จัดกลุ่มเอนด์พอยต์ลงในโฟลเดอร์ และปรับแต่งรายละเอียดที่อนุมานโดยอัตโนมัติ

4. ส่งออก Spec: เมื่อคอลเลกชันของคุณถูกต้องและมีคำอธิบายที่ดี คุณก็สามารถส่งออกได้ และผู้ใช้สามารถส่งออก OpenAPI specs ในรูปแบบ YAML หรือ JSON มาตรฐานได้ด้วยการคลิกเพียงครั้งเดียว Spec นี้พร้อมที่จะนำไปใช้กับ Swagger UI, นำเข้าเครื่องมืออื่นๆ หรือคอมมิตไปยัง repository ของคุณ

ข้อดี:

• เวิร์กโฟลว์ที่เป็นธรรมชาติ: เข้ากับวิธีการทำงานของนักพัฒนาอยู่แล้ว (การทดสอบ API)
• การควบคุมสูง: คุณดูแลและปรับแต่ง spec ขณะที่คุณสร้างคอลเลกชัน
• ครอบคลุม: คุณสามารถมั่นใจได้ว่าเอนด์พอยต์, การตอบสนองข้อผิดพลาด และวิธีการตรวจสอบสิทธิ์ทั้งหมดได้รับการจัดทำเป็นเอกสาร
• ทำงานร่วมกันได้: ทีมสามารถทำงานร่วมกันในคอลเลกชันคำขอเดียวกันได้

ข้อเสีย:

• ต้องใช้ความพยายามด้วยตนเอง: คุณต้องแน่ใจว่าคุณครอบคลุมเอนด์พอยต์ทั้งหมดแล้ว มันไม่ได้เป็นไปโดยอัตโนมัติทั้งหมดจากทราฟฟิก

วิธีที่ 4: แนวทาง "การสร้างด้วยตนเอง"

บางครั้ง คุณอาจต้องสร้าง spec ด้วยตนเองใน editor เช่น Swagger Editor หรือ Stoplight Studio ซึ่งมักจะทำควบคู่ไปกับวิธีการข้างต้น

1. ใช้คอลเลกชันคำขอของคุณเป็นข้อมูลอ้างอิง: เปิดคอลเลกชัน Postman, คำสั่ง cURL หรือโปรเจกต์ Apidog ของคุณบนหน้าจอที่สอง
2. สร้าง Spec ทีละขั้นตอน: สำหรับแต่ละเอนด์พอยต์ในข้อมูลอ้างอิงของคุณ ให้แปลเป็น OpenAPI YAML/JSON ด้วยตนเอง ซึ่งจะบังคับให้คุณคิดอย่างละเอียดเกี่ยวกับแต่ละพารามิเตอร์และการตอบกลับ
3. ตรวจสอบความถูกต้องด้วยตัวอย่าง: ใช้พรีวิวของ editor เพื่อให้แน่ใจว่า spec ของคุณตรงกับพฤติกรรม API จริง

ข้อดี:

• ความเข้าใจอย่างลึกซึ้ง: คุณจะรู้ทุกรายละเอียดของ spec ของคุณ
• ความแม่นยำสูงสุด: คุณสามารถจัดทำเอกสารเกี่ยวกับความละเอียดอ่อนที่เครื่องมืออัตโนมัติอาจพลาดไป

ข้อเสีย:

• ใช้เวลานานมาก: เป็นวิธีที่ต้องใช้แรงงานมากที่สุด
• เกิดข้อผิดพลาดได้ง่าย: อาจพิมพ์ผิดหรือลืมเอนด์พอยต์ได้ง่าย

แนวทางปฏิบัติที่ดีที่สุดสำหรับการสร้าง OpenAPI Specs จากคำขอ

ไม่ว่าคุณจะใช้วิธีใด ให้ปฏิบัติตามหลักการเหล่านี้:

1. เริ่มต้นด้วยขนาดเล็ก: เลือกเอนด์พอยต์หลักหนึ่งรายการ (เช่น GET /users) สร้างหรือจัดทำเอกสารให้สมบูรณ์ จากนั้นค่อยขยาย
2. ตรวจสอบความถูกต้องแต่เนิ่นๆ และบ่อยครั้ง: ใช้ OpenAPI spec เพื่อสร้าง mock server ทันที มันทำงานเหมือน API จริงของคุณหรือไม่? สิ่งนี้ช่วยตรวจจับความไม่ตรงกันได้อย่างรวดเร็ว
3. ทำซ้ำและปรับปรุง: spec ที่สร้างขึ้นครั้งแรกของคุณจะยังไม่สมบูรณ์ ถือว่าเป็นฉบับร่าง เพิ่มคำอธิบาย, ตัวอย่าง และปรับปรุงการกำหนด schema ให้กระชับขึ้น
4. รวมการตอบสนองข้อผิดพลาด: ข้อนี้มักถูกละเลย ตรวจสอบให้แน่ใจว่า spec ของคุณจัดทำเอกสารรูปแบบการตอบสนองข้อผิดพลาด 4xx และ 5xx
5. อย่าลืมการตรวจสอบสิทธิ์: จัดทำเอกสารวิธีการรักษาความปลอดภัย API ของคุณ (API Key, OAuth2 เป็นต้น) ในส่วน securitySchemes

สรุป: แบบพิมพ์เขียวของคุณกำลังรออยู่

การสร้าง OpenAPI specification จากคำขอที่มีอยู่ไม่เพียงแต่เป็นไปได้เท่านั้น แต่ยังเป็นสิ่งจำเป็นในทางปฏิบัติสำหรับการจัดระเบียบโครงการ API ที่เติบโตเต็มที่ ไม่ว่าคุณจะเลือกไลบรารีแบบ code-first, เครื่องมือดักจับทราฟฟิก หรือไคลเอนต์ API ที่ทรงพลังอย่าง Apidog คุณกำลังลงทุนในความชัดเจน, ระบบอัตโนมัติ และการทำงานร่วมกัน

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

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