วิธีออกแบบ API จาก CLI

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

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

คู่มือนี้มีสองเส้นทาง อย่างแรกคือเส้นทางโอเพนซอร์สทั่วไปที่สร้างขึ้นจากเครื่องมือเฉพาะทาง: สร้างไฟล์ OpenAPI ตรวจสอบไวยากรณ์ด้วย Spectral รวมเข้ากับ Redocly CLI และสร้างส่วนขยายเซิร์ฟเวอร์ด้วย openapi-generator จากนั้นเป็นเส้นทาง Apidog CLI ซึ่งการออกแบบ สคีมา จุดสิ้นสุด และการตรวจสอบสิทธิ์อยู่ในโปรเจ็กต์เดียวที่คุณสามารถจัดการได้จากเทอร์มินัล หากคุณต้องการพื้นฐานแนวคิดที่ลึกซึ้งยิ่งขึ้นก่อน โปรดอ่านคู่มือของเราเกี่ยวกับ วิธีออกแบบ API และคำแนะนำเกี่ยวกับ การออกแบบ REST API

หากคุณกำลังทำตามด้วย Apidog ให้ดาวน์โหลดไบนารีมาก่อน คู่มือการติดตั้ง Apidog CLI ของเราครอบคลุมขั้นตอน npm install -g apidog-cli และการเชื่อมต่อ apidog login --with-token และ คู่มือ Apidog CLI ฉบับสมบูรณ์ จะแสดงกลุ่มคำสั่งทั้งหมด

เส้นทางโอเพนซอร์สทั่วไป: สร้าง, ตรวจสอบไวยากรณ์, รวม, สร้าง

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

สร้างเอกสาร OpenAPI

คุณเริ่มต้นด้วยไฟล์ YAML ธรรมดา ไม่จำเป็นต้องมีตัวแก้ไขพิเศษ ตัวแก้ไขข้อความใดก็ได้ใช้ได้ openapi.yaml ที่น้อยที่สุดมีลักษณะดังนี้:

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]

เมื่อ API เติบโตขึ้น คุณจะแยก API ออกเป็นหลายไฟล์และอ้างอิงด้วย $ref สิ่งนี้ช่วยให้แต่ละสคีมาสามารถอ่านและตรวจสอบได้ด้วยตัวเอง

ตรวจสอบไวยากรณ์ด้วย Spectral

OpenAPI ที่เขียนด้วยมือมักจะผิดเพี้ยน บางคนลืม operationId อีกคนไม่ได้บันทึกการตอบกลับ คนที่สามคิดค้นรูปแบบการตั้งชื่อของตัวเอง ตัวตรวจสอบไวยากรณ์จะตรวจจับสิ่งเหล่านั้นทั้งหมดก่อนการตรวจสอบ Spectral จาก Stoplight เป็นตัวเลือกมาตรฐาน มีชุดกฎสำหรับ OpenAPI และให้คุณเขียนกฎของคุณเองได้

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Spectral จะพิมพ์การละเมิดแต่ละรายการพร้อมหมายเลขบรรทัดและความรุนแรง คุณสามารถทำให้บิลด์ล้มเหลวเมื่อมีข้อผิดพลาดโดยการตรวจสอบรหัสออกใน CI Redocly's CLI และ vacuum ทำงานเดียวกันได้ หากคุณต้องการทางเลือกอื่น vacuum ทำงานได้เร็วและเป็นตัวตรวจสอบไวยากรณ์ที่เข้ากันได้กับ Spectral ประเด็นสำคัญยังคงอยู่ไม่ว่าคุณจะเลือกอันไหน: การตรวจสอบไวยากรณ์เป็นเครื่องมือแยกต่างหากและเฉพาะทาง และคุณเรียกใช้เป็นขั้นตอนของตัวเอง

รวมเข้าด้วยกันด้วย Redocly CLI

เมื่อคำจำกัดความของคุณถูกแบ่งออกเป็นหลายไฟล์ เครื่องมือปลายน้ำส่วนใหญ่ต้องการเอกสารเดียวที่รวมอยู่ในตัวเอง Redocly CLI จะแก้ไข $ref ทุกตัวและทำให้ต้นไม้แบนราบลงในไฟล์เดียว

npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

Redocly ยังตรวจสอบ (redocly lint) และแสดงตัวอย่างเอกสาร ดังนั้นบางทีมจึงใช้ทั้งการตรวจสอบสไตล์และการรวมเข้าด้วยกัน เอกสารทางการ ของมันแสดงชุดคำสั่งทั้งหมด

สร้างส่วนขยายด้วย openapi-generator

ด้วยข้อมูลจำเพาะที่สะอาดและรวมเข้าด้วยกัน คุณสามารถสร้างโค้ดได้ openapi-generator จะแปลงเอกสาร OpenAPI ให้เป็นส่วนขยายเซิร์ฟเวอร์, SDK ไคลเอนต์ และอื่น ๆ อีกมากมายในหลายสิบภาษา

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server

สลับ -g spring เป็น -g python-flask, -g go-server, หรือเครื่องมือสร้างที่รองรับอื่นๆ ตอนนี้คุณมีโครงสร้างที่ตรงกับสัญญาของคุณอย่างสมบูรณ์

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

เส้นทาง Apidog CLI: การออกแบบในโปรเจ็กต์เดียว

แนวทางอื่นคือการเก็บการออกแบบ สคีมา จุดสิ้นสุด การจำลอง และการรับรองความถูกต้องไว้ในโปรเจ็กต์เดียวที่คุณจัดการจากเทอร์มินัล ไบนารี apidog-cli เป็น CLI ทรัพยากรโปรเจ็กต์ที่สมบูรณ์ ไม่ใช่แค่ตัวรันการทดสอบเท่านั้น มีกลุ่มคำสั่งสำหรับพื้นผิวการออกแบบทั้งหมด: schema สำหรับโมเดลข้อมูล, endpoint สำหรับการดำเนินการ, folder สำหรับการจัดระเบียบ, security-scheme สำหรับการรับรองความถูกต้อง, รวมถึง import, export, mock และอื่นๆ

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

ติดตั้งและยืนยันตัวตนก่อน (ดู คู่มือการติดตั้ง สำหรับการตั้งค่าโทเค็น):

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

ทุกคำสั่งจะคืนค่า JSON ที่มีโครงสร้าง และการตอบกลับส่วนใหญ่จะมีบล็อก agentHints.nextSteps ที่จะบอกคุณ (หรือเอเจนต์) ว่าจะเรียกใช้สิ่งใดต่อไป เพิ่ม --help ให้กับคำสั่งใดๆ เพื่อดูแฟล็กที่แน่นอน

กำหนดโมเดลข้อมูลด้วย apidog schema

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

apidog schema --help
apidog schema create --project <PROJECT_ID>

เนื่องจากผลลัพธ์เป็น JSON คุณสามารถส่งผ่าน jq เพื่อดึง ID ของสคีมาใหม่และส่งต่อไปยังคำสั่งถัดไปได้ หากคุณมีไฟล์ OpenAPI อยู่แล้ว ให้นำเข้าแทนที่จะพิมพ์ใหม่ทั้งหมด:

apidog import --project <PROJECT_ID> --file openapi.yaml

apidog import รองรับ OpenAPI 3.x, Swagger 2.0, Postman และรูปแบบ Apidog ดังนั้นคำจำกัดความที่มีอยู่จะกลายเป็นโปรเจ็กต์จริงได้ในขั้นตอนเดียว

กำหนดจุดสิ้นสุดด้วย apidog endpoint

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

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>

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

กำหนดการรับรองความถูกต้องด้วย apidog security-scheme

การรับรองความถูกต้องเป็นส่วนหนึ่งของสัญญา ไม่ใช่ความคิดที่มาทีหลัง กลุ่ม security-scheme กำหนดวิธีการที่ไคลเอ็นต์จะตรวจสอบสิทธิ์: คีย์ API, โทเค็นผู้ถือ, OAuth 2.0 และอื่นๆ สิ่งนี้จะจับคู่กับ components/securitySchemes ใน OpenAPI ดังนั้นการนำเข้าและส่งออกจึงสามารถทำไปกลับได้อย่างราบรื่น

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>

การกำหนด scheme ครั้งเดียวที่ระดับโปรเจ็กต์หมายความว่าทุกปลายทางสามารถอ้างอิงถึงมันได้ แทนที่จะต้องประกาศ auth ใหม่ในแต่ละการดำเนินการ นั่นคือความสอดคล้องแบบเดียวกับที่ linter จะเตือนคุณถึงความไม่สอดคล้องกัน

ตรวจสอบความถูกต้องของการเขียนของคุณด้วย apidog cli-schema validate

ก่อนที่คุณจะคอมมิตการเปลี่ยนแปลงหรือส่งโปรเจกต์ไปยัง CI คุณต้องการทราบว่าคำจำกัดความทรัพยากรของคุณมีรูปแบบที่ถูกต้อง CLI มีคำสั่ง cli-schema validate ที่ตรวจสอบไฟล์คำจำกัดความกับสคีมาที่ CLI คาดหวัง เพื่อให้การเขียนที่ผิดพลาดล้มเหลวอย่างรวดเร็วแทนที่จะเกิดขึ้นอย่างเงียบๆ

apidog cli-schema --help
apidog cli-schema validate --file resource.json

เรียกใช้สิ่งนี้เป็นขั้นตอนการป้องกันในไปป์ไลน์ของคุณ: ตรวจสอบความถูกต้องก่อน แล้วจึงนำไปใช้ การออกที่ไม่ใช่ศูนย์จะหยุดไปป์ไลน์ก่อนที่ทรัพยากรที่ไม่ดีจะไปถึงโปรเจกต์ นี่คือการตรวจสอบความถูกต้องของการเขียน CLI ของคุณ ไม่ใช่การตรวจสอบไวยากรณ์สไตล์ OpenAPI งานทั้งสองอย่างนี้แตกต่างกัน และคุณยังคงต้องการ Spectral สำหรับงานที่สอง

ส่งออกกลับไปเป็น OpenAPI

ออกแบบใน Apidog จากนั้นส่งมอบอาร์ติแฟกต์มาตรฐานให้กับชุดเครื่องมือที่เหลือของคุณ apidog export เขียน OpenAPI, HTML, Markdown หรือ Postman

apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml

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

เชื่อมโยงเข้ากับ CI

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

# ล้มเหลวเมื่อมีข้อผิดพลาดด้านสไตล์
spectral lint openapi.yaml

# ตรวจสอบความถูกต้องของการเขียนทรัพยากร CLI ก่อนนำไปใช้
apidog cli-schema validate --file resource.json

# รวมให้เป็นอาร์ติแฟกต์เดียวสำหรับขั้นตอนปลายน้ำ
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

เนื่องจากเอาต์พุตของ Apidog เป็น JSON พร้อมกับ agentHints.nextSteps การไหลนี้จึงสามารถขับเคลื่อนได้อย่างราบรื่นจากเอเจนต์การเขียนโค้ด AI ตัวเอเจนต์จะอ่านผลลัพธ์ที่มีโครงสร้าง เห็นขั้นตอนถัดไปที่แนะนำ และเรียกใช้ โดยไม่ต้องอาศัยการสแกนหน้าจอ GUI นั่นคือเหตุผลทั้งหมดในการออกแบบจาก CLI ตั้งแต่แรก: สิ่งที่มนุษย์พิมพ์ สคริปต์หรือเอเจนต์ก็สามารถพิมพ์ได้เช่นกัน

ปัญหาที่พบบ่อย

การแยกไฟล์ทำให้เครื่องมือปลายน้ำใช้งานไม่ได้ คำจำกัดความที่กระจายอยู่ทั่วไฟล์ $ref จำนวนมากนั้นดีสำหรับมนุษย์ แต่ยุ่งยากสำหรับเครื่องมือสร้างโค้ด ควรมัดรวมเป็นไฟล์เดียวเสมอก่อนที่คุณจะสร้างโค้ดหรือเผยแพร่เอกสาร redocly bundle คือวิธีแก้ปัญหา

คุณคาดหวังให้ Apidog ตรวจสอบไวยากรณ์ แต่มันจะไม่ทำ Apidog จัดการทรัพยากร ไม่ได้บังคับใช้คู่มือสไตล์หรือตั้งค่าสถานะการละเมิดกฎ OpenAPI ให้ใช้ Spectral หรือ vacuum สำหรับสิ่งนั้น การถือว่า apidog cli-schema validate เป็นตัวตรวจสอบไวยากรณ์คือความเข้าใจผิดที่พบบ่อย มันตรวจสอบโครงสร้างทรัพยากร ไม่ใช่สไตล์ OpenAPI

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

การรับรองความถูกต้องที่กำหนดตามจุดสิ้นสุดแทนที่จะกำหนดเพียงครั้งเดียว กำหนด security-scheme ที่ระดับโปรเจ็กต์และอ้างอิงถึงมัน การประกาศการรับรองความถูกต้องซ้ำในทุกการดำเนินการจะทำให้เกิดความคลาดเคลื่อนของสัญญา

สรุป

การออกแบบ API จาก CLI เปลี่ยนงานที่ต้องคลิกเยอะๆ ให้เป็นชุดคำสั่งที่ทำซ้ำได้ เส้นทางโอเพนซอร์ส การสร้าง การตรวจสอบไวยากรณ์ด้วย Spectral การรวมเข้าด้วย Redocly การสร้างด้วย openapi-generator ทำให้คุณสามารถควบคุมได้อย่างเต็มที่และไม่มีการผูกขาด เส้นทาง Apidog CLI ทำให้คุณมีโปรเจกต์แบบรวมที่สคีมา จุดสิ้นสุด และการตรวจสอบสิทธิ์อยู่รวมกัน และทุกคำสั่งจะส่งคืน JSON ที่พร้อมสำหรับเอเจนต์ การส่งออกทำหน้าที่เป็นสะพานเชื่อมระหว่างทั้งสอง ดังนั้นคุณจะไม่มีทางติดขัด

เลือกเส้นทางที่ตรงกับทีมของคุณ หากคุณอยู่ใน Git อยู่แล้วและมีเครื่องมือเฉพาะทางหลายชิ้น ให้ใช้เครื่องมือเหล่านั้นต่อไปและเพิ่ม apidog export เมื่อคุณต้องการอาร์ติแฟกต์ที่สามารถพกพาได้ หากคุณไม่อยากดูแลส่วนเชื่อมต่อ ดาวน์โหลด Apidog ติดตั้ง CLI และออกแบบ API ถัดไปของคุณโดยไม่ต้องสัมผัสเมาส์