วิศวกรสองคนในทีมเดียวกันได้ส่งมอบสองเอนด์พอยต์ในสัปดาห์เดียวกัน หนึ่งตัวส่งคืน created_at อีกตัวส่งคืน createdAt หนึ่งตัวแบ่งหน้าด้วย ?page=2 อีกตัวด้วย ?offset=20 หนึ่งตัวใส่ข้อผิดพลาดในออบเจกต์ error ระดับบนสุด อีกตัวใส่ข้อความ message แบบอินไลน์ ทั้งสองผ่านการตรวจโค้ด เพราะผู้ตรวจสอบอ่านตรรกะ ไม่ใช่วิธีการตั้งชื่อ หกเดือนต่อมา API ของคุณก็ดูเหมือนเขียนโดยบริษัทห้าแห่งที่แตกต่างกัน และการเชื่อมต่อกับไคลเอ็นต์แต่ละรายก็ต้องการกรณีพิเศษ
OpenAPI linter มีอยู่เพื่อตรวจจับความผิดเพี้ยนนั้นก่อนที่จะถูกนำไปใช้งาน มันจะอ่านเอกสาร OpenAPI ของคุณ รันเอกสารนั้นกับชุดกฎ (การดำเนินการต้องมีคำอธิบาย, สคีมาต้องมีตัวอย่าง, ชื่อคุณสมบัติต้องเป็นไปตามรูปแบบการตั้งชื่อ, ทุกการตอบสนองต้องประกาศประเภทสื่อ) และจะทำให้บิลด์ล้มเหลวเมื่อมีการละเมิดกฎ นี่เป็นแนวคิดเดียวกับ ESLint สำหรับ JavaScript หรือ RuboCop สำหรับ Ruby โดยชี้ไปที่สัญญา API ของคุณแทนที่จะเป็นโค้ดแอปพลิเคชันของคุณ หากคุณเคยหวังว่าการตรวจสอบการออกแบบ API จะสามารถทำให้เป็นอัตโนมัติได้เหมือนกับการจัดรูปแบบโค้ด นั่นคือสิ่งที่ linter ทำได้อย่างแท้จริง
สิ่งที่ OpenAPI linter ตรวจสอบจริง ๆ
linter ทำงานกับไฟล์สเปก ไม่ใช่บนเซิร์ฟเวอร์ที่กำลังทำงานอยู่ ชี้ไปที่ openapi.yaml แล้วมันจะตรวจสอบทุกเส้นทาง, การดำเนินการ, พารามิเตอร์, สคีมา และการตอบสนอง โดยใช้กฎทีละข้อ กฎแบ่งออกเป็นสองสามประเภท
ความถูกต้อง. นี่เป็นเอกสาร OpenAPI ที่ถูกต้องตามกฎหมายหรือไม่? $ref ทุกตัวแก้ปัญหาได้หรือไม่? คีย์เวิร์ดที่จำเป็นมีอยู่หรือไม่? สิ่งนี้ทับซ้อนกับการตรวจสอบความถูกต้องของสคีมาทั่วไป และ linter ส่วนใหญ่จะทำสิ่งนี้เป็นพื้นฐานก่อนสิ่งอื่นใด
ความสมบูรณ์. ทุกการดำเนินการมี operationId, สรุป และคำอธิบายหรือไม่? ทุกพารามิเตอร์อธิบายตัวเองได้หรือไม่? ทุกสคีมามี example หรือไม่? นี่คือกฎที่ทำให้เอกสารและ SDK ที่สร้างขึ้นสามารถใช้งานได้จริง และเป็นสิ่งที่มนุษย์มักจะลืมมากที่สุด
ความสอดคล้อง. นี่คือรางวัลที่แท้จริง ชื่อคุณสมบัติใช้รูปแบบการตั้งชื่อเดียวกัน ส่วนของเส้นทางเป็นคำนามพหูพจน์ การตอบสนองข้อผิดพลาดมีรูปแบบเดียวกัน ทุกการตอบสนอง 2xx ประกาศ application/json รหัสสถานะถูกใช้ตามที่ HTTP spec ตั้งใจไว้ สิ่งเหล่านี้ไม่ใช่ข้อบกพร่องโดด ๆ แต่เมื่อรวมกันแล้ว มันคือความแตกต่างระหว่าง API ที่ให้ความรู้สึกว่าถูกออกแบบมาอย่างดีกับ API ที่ให้ความรู้สึกว่าถูกประกอบขึ้นมา
สไตล์ภายในองค์กร. ข้อกำหนดของคุณเอง บางทีทุกเอนด์พอยต์ต้องมีแท็ก บางที DELETE ต้องส่งคืน 204 บางทีฟิลด์สำหรับใช้ภายในเท่านั้นต้องมีคำนำหน้า สิ่งเหล่านี้คือกฎที่ไม่มีใครมี และความสามารถในการเขียนกฎเหล่านี้คือสิ่งที่แยก linter ที่คุณสามารถอยู่ร่วมกับมันได้ ออกจาก linter ที่คุณต้องต่อสู้ด้วย
กฎมีความร้ายแรง: error (ข้อผิดพลาด), warning (คำเตือน), info (ข้อมูล), หรือ hint (คำแนะนำ) Error จะทำให้บิลด์ล้มเหลว; warning จะแสดงขึ้นแต่ยังคงปล่อยให้ผ่านไปได้ การปรับระดับความร้ายแรงนี้เองที่ทำให้คุณสามารถนำ linting มาใช้กับ API ที่มีอยู่แล้วได้โดยไม่จมอยู่กับข้อผิดพลาด 4,000 รายการตั้งแต่วันแรก เริ่มต้นทุกอย่างเป็น warning แก้ไขสิ่งที่แย่ที่สุด แล้วจึงค่อย ๆ เลื่อนระดับกฎให้เป็น error เมื่อคุณทำไปเรื่อย ๆ สำหรับด้านแนวคิดว่าทำไมกฎเหล่านี้จึงสำคัญ และทีมงานบังคับใช้กฎเหล่านี้ในวงกว้างได้อย่างไร ข้อมูลเชิงลึกเพิ่มเติมอยู่ใน วิธีที่บริษัทชั้นนำสร้างความสอดคล้องในการออกแบบ API
ตัวเลือก OpenAPI linter หลัก ๆ
นี่คือเครื่องมือที่ควรรู้ พร้อมกับการประเมินอย่างตรงไปตรงมาว่าแต่ละตัวเหมาะกับอะไร
Spectral
Spectral จาก Stoplight เป็นมาตรฐานโดยพฤตินัย มันเป็น CLI และไลบรารีโอเพนซอร์สที่ใช้ linting กับ OpenAPI 2.0 และ 3.x (และ AsyncAPI รวมถึง JSON หรือ YAML ใด ๆ ผ่าน JSONPath) มันมาพร้อมกับชุดกฎ spectral:oas ที่ครอบคลุมกฎสามัญสำนึกทั่วไป และจุดแข็งที่แท้จริงของมันคือกฎที่กำหนดเอง: คุณอธิบายสิ่งที่ต้องการตรวจสอบโดยใช้ตัวเลือก given สไตล์ JSONPath และฟังก์ชัน then ทั้งหมดอยู่ในไฟล์ YAML มีแคตตาล็อกฟังก์ชันในตัวจำนวนมาก (truthy, pattern, casing, length, enumeration) และคุณสามารถใช้ JavaScript ได้เมื่อคุณต้องการตรรกะที่รูปแบบ declarative ไม่สามารถแสดงออกได้
จุดแข็ง: มีอยู่ทั่วไป มีระบบนิเวศกฎที่ใหญ่ที่สุด มีส่วนขยายสำหรับ VS Code และอื่น ๆ และทำงานได้ทุกที่ที่ Node ทำงาน หากคุณต้องการเครื่องมือเดียวที่ทั้งอุตสาหกรรมรู้จัก นี่คือคำตอบ ข้อแลกเปลี่ยนคือการเขียนกฎที่ไม่ซับซ้อนหมายถึงการเรียนรู้ JSONPath และในที่สุดก็คือ Spectral’s function API เรามีคำแนะนำโดยละเอียดเกี่ยวกับเรื่องนั้นใน การสร้างกฎ Spectral แบบกำหนดเองด้วย TypeScript หากคุณต้องการเจาะลึกในการเขียน
extends: ["spectral:oas"]
rules:
operation-operationId: error
operation-description: warn
property-casing:
description: Properties must be camelCase
given: $.components.schemas..properties[*]~
severity: error
then:
function: casing
functionOptions:
type: camel
รันมัน:
npx @stoplight/spectral-cli lint openapi.yaml
Redocly CLI
Redocly’s CLI รวมการทำ linting เข้ากับการทำ bundling และการแสดงตัวอย่างเอกสาร linter ของมันอ่านการกำหนดค่า redocly.yaml มาพร้อมกับชุดกฎในตัว และรองรับชุดกฎที่กำหนดค่าได้ พร้อมทั้งปลั๊กอินแบบกำหนดเองที่เขียนด้วย JavaScript ทีมที่ใช้ Redocly สำหรับเอกสารอยู่แล้วจะได้การทำ linting ในชุดเครื่องมือเดียวกันโดยไม่ต้องเพิ่ม dependency และกฎในตัวมักจะเน้นไปที่สิ่งที่ทำให้เอกสารแสดงผลได้ดี
จุดแข็ง: การผสานรวมอย่างแน่นหนากับเวิร์กโฟลว์เอกสารและการทำ bundling, ค่าเริ่มต้นที่ดี, และรูปแบบการกำหนดค่าที่คุ้นเคยหากคุณอยู่ในระบบนิเวศของ Redocly หากคุณยังไม่ได้อยู่ที่นั่น ไลบรารีกฎจะเล็กกว่าของ Spectral และการสร้างกฎแบบกำหนดเองก็มีเอกสารน้อยกว่า
npx @redocly/cli lint openapi.yaml
Vacuum
Vacuum เป็น linter ใหม่กว่าที่เขียนด้วย Go สร้างขึ้นเพื่อความเร็ว มันเข้ากันได้กับชุดกฎของ Spectral ดังนั้นคุณสามารถชี้ไปที่ไฟล์ .spectral.yaml ที่มีอยู่และได้รับการตรวจสอบแบบเดียวกันที่ทำงานได้เร็วกว่ามากสำหรับสเปกขนาดใหญ่ สำหรับ monorepo ที่มีเอกสาร API ขนาดใหญ่หลายสิบฉบับ ความแตกต่างของเวลาทำงานนั้นเป็นของจริง
จุดแข็ง: เร็ว, เข้ากันได้กับชุดกฎของ Spectral, เป็นไบนารีเดียวโดยไม่มี Node runtime หากสเปกของคุณมีขนาดเล็ก ประสิทธิภาพความเร็วที่เพิ่มขึ้นจะมองไม่เห็น และระบบนิเวศและเครื่องมือแก้ไขก็ยังใหม่กว่าของ Spectral ดังนั้นจึงน่าสนใจที่สุดในฐานะตัวเร่งความเร็ว CI มากกว่าการเลือกใช้ตั้งแต่เริ่มต้น
Swagger และ openapi-spec-validator
ควรกล่าวถึงเพื่อไม่ให้สับสนกับ linters. Swagger Editor และ swagger-cli/openapi-spec-validator ตรวจสอบว่าเอกสารเป็น OpenAPI ที่ถูกต้องหรือไม่ นั่นคือการตรวจสอบความถูกต้องเท่านั้น ไม่ใช่ความสอดคล้องหรือสไตล์ภายในองค์กร พวกมันจะยอมรับสเปกที่ทุกคุณสมบัติมีชื่อต่างกันได้อย่างมีความสุข เพราะไม่มีสิ่งใดในข้อกำหนด OpenAPI ที่ห้ามสิ่งนั้น การตรวจสอบความถูกต้องเป็นสิ่งจำเป็น แต่มันเป็นแค่ขั้นต่ำสุด ไม่ใช่ขั้นสูงสุด หากคุณกำลังเลือกระหว่างเครื่องมือตระกูล Swagger กับแพลตฟอร์มการออกแบบเต็มรูปแบบ ข้อดีข้อเสียจะถูกอธิบายไว้ใน ทางเลือกของ Swagger ที่ทดสอบ API ของคุณได้ด้วย
การตรวจสอบในขณะออกแบบใน Apidog
เครื่องมือข้างต้นจะทำงานหลังจากที่คุณมีไฟล์แล้ว อีกจุดหนึ่งในการจับความไม่สอดคล้องคือ ก่อนที่ไฟล์จะถูกสร้างขึ้น ในขณะที่คุณกำลังออกแบบเอนด์พอยต์ Apidog เป็นแพลตฟอร์มที่เน้นการออกแบบเป็นอันดับแรก: คุณสร้างเอนด์พอยต์และสคีมาข้อมูลในโปรแกรมแก้ไขแบบภาพ และมันจะรักษาความสอดคล้องภายในของโปรเจกต์ของคุณไปพร้อมกัน สคีมาข้อมูลที่นำกลับมาใช้ใหม่ได้หมายความว่าโมเดลเดียวกันจะถูกอ้างอิงอยู่ทุกที่ แทนที่จะถูกนิยามใหม่สำหรับแต่ละเอนด์พอยต์ ซึ่งช่วยขจัดปัญหาการตั้งชื่อที่ผิดเพี้ยนไปตั้งแต่ต้น ส่วนประกอบการตอบสนองที่ใช้ร่วมกันก็ทำหน้าที่เดียวกันสำหรับรูปแบบข้อผิดพลาด
Apidog ไม่ใช่ตัวแทนโดยตรงสำหรับชุดกฎ Spectral; หากคุณได้คอมมิตกฎ .spectral.yaml ไว้แล้ว ให้รันต่อไป สิ่งที่ Apidog เปลี่ยนแปลงคือปริมาณที่ linter ของคุณค้นพบตั้งแต่แรก เมื่อพื้นผิวการออกแบบบังคับใช้การนำกลับมาใช้ใหม่ linter จะเปลี่ยนจากกำแพงแห่งการละเมิดเป็นเพียงการจับผิดเล็กน้อยเป็นครั้งคราว และเนื่องจาก Apidog นำเข้าและส่งออก OpenAPI 3.x มาตรฐาน ไฟล์ที่คุณส่งให้ Spectral หรือ Vacuum ใน CI จึงเป็นไฟล์เดียวกัน ดังนั้นสองเลเยอร์นี้จึงทำงานร่วมกันแทนที่จะแข่งขันกัน
การตั้งค่า linter ที่คุณสามารถใช้งานได้วันนี้
การตั้งค่าที่ดีจะทำการตรวจสอบในสามที่ โดยแต่ละที่มีหน้าที่ต่างกัน โปรแกรมแก้ไขให้ผลตอบรับทันที pre-commit hook หยุดข้อผิดพลาดที่ชัดเจนในเครื่อง CI คือประตูที่ไม่มีใครสามารถข้ามได้ นี่คือแต่ละเลเยอร์
เลเยอร์ 1: โปรแกรมแก้ไข
ติดตั้งส่วนขยาย Spectral VS Code และเพิ่มไฟล์ .spectral.yaml ไปยัง root ของ repo ของคุณ ส่วนขยายจะตรวจจับได้โดยอัตโนมัติและขีดเส้นใต้การละเมิดขณะที่คุณแก้ไขสเปก เหมือนกับการพิมพ์ผิดที่ขึ้นขีดเส้นใต้สีแดง นี่คือวงจรการตอบรับที่ถูกที่สุดที่เป็นไปได้ เพราะนักพัฒนาแก้ไขปัญหาก่อนที่จะกลายเป็น commit ไม่มีการตั้งค่าอื่นใด; ไฟล์ใน repo เป็นแหล่งความจริงเดียวสำหรับกฎเกณฑ์
เลเยอร์ 2: pre-commit
เพิ่ม hook เพื่อให้สเปกที่เสียหายไม่ถูกส่งไปยัง remote การใช้สคริปต์ package.json บวกกับ Git hook ก็เพียงพอแล้ว:
{
"scripts": {
"lint:api": "spectral lint openapi.yaml --fail-severity=error"
}
}
# .git/hooks/pre-commit (or via husky)
#!/bin/sh
npm run lint:api || {
echo "OpenAPI lint failed. Fix the spec before committing."
exit 1
}
แฟล็ก --fail-severity=error เป็นส่วนที่สำคัญ มันบอกให้ linter ออกจากการทำงานด้วยรหัสที่ไม่ใช่ศูนย์เฉพาะเมื่อมีข้อผิดพลาดเท่านั้น ดังนั้นคำเตือนยังคงแสดงผลโดยไม่บล็อกการ commit นั่นทำให้ hook ยังคงใช้งานได้ในขณะที่คุณกำลังเลื่อนระดับกฎ
เลเยอร์ 3: CI
นี่คือประตูที่สำคัญ เพราะเป็นประตูที่เพื่อนร่วมทีมไม่สามารถข้ามได้ด้วย --no-verify ขั้นตอน GitHub Actions:
name: API lint
on: [pull_request]
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=error
งานจะล้มเหลวเมื่อสเปกละเมิดกฎระดับข้อผิดพลาด, pull request จะแสดงเครื่องหมายสีแดง, และการรวมโค้ดจะถูกบล็อกจนกว่าจะมีคนแก้ไข นั่นคือกลไกการบังคับใช้ทั้งหมด ไม่มีแดชบอร์ด ไม่มีการจู้จี้จุกจิก; กฎจะเป็นสีเขียวหรือไม่ก็ไม่เป็น
เลเยอร์ 4: ทดสอบ API ที่สเปกอธิบาย
linter พิสูจน์ว่าสเปกมีรูปแบบที่ดีและสอดคล้องกัน มันไม่ได้บอกอะไรเกี่ยวกับการที่ API ที่กำลังทำงานอยู่ตรงกับสเปกหรือไม่ ช่องว่างนั้นคือที่ที่ความผิดเพี้ยนของสัญญาซ่อนอยู่: เอกสารที่ผ่านการ lint อย่างสวยงามอธิบายพฤติกรรมที่เซิร์ฟเวอร์หยุดให้ความสำคัญเมื่อสามเวอร์ชันที่แล้ว เพื่อปิดช่องว่างนี้ คุณต้องรันการทดสอบกับ API ที่ใช้งานจริงในไปป์ไลน์เดียวกัน
นี่คือจุดที่ Apidog CLI เข้ามาทำงานควบคู่กับ linter ของคุณ มันเป็นแพ็กเกจ npm ชื่อ apidog-cli และมันจะรันสถานการณ์การทดสอบ Apidog ของคุณจาก command line เพื่อให้สามารถเสียบเข้าไปใน CI ได้ทันทีหลังขั้นตอน lint:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
คำสั่ง apidog run จะออกด้วยค่าที่ไม่ใช่ศูนย์เมื่อการทดสอบล้มเหลว ซึ่งเป็นสัญญาเดียวกันที่ทุกขั้นตอน CI ใช้ ดังนั้นการทดสอบที่ล้มเหลวจะบล็อกการรวมโค้ดเช่นเดียวกับการ lint ที่ล้มเหลว ตัวรายงาน -r junit จะส่งออก XML ที่แดชบอร์ด CI ของคุณสามารถแยกวิเคราะห์เป็นแผนผังผ่าน/ไม่ผ่าน และ -e ชี้สถานการณ์เดียวกันไปยัง staging หรือ production โดยไม่ต้องทำซ้ำ CLI ยังสามารถ import เอกสาร OpenAPI 3.x ได้ ดังนั้นไฟล์ที่ linter ของคุณตรวจสอบก็จะเป็นไฟล์เดียวกับที่ Apidog ใช้ทดสอบ สำหรับรูปแบบไปป์ไลน์ที่สมบูรณ์ รวมถึงตัวรายงานและการจัดการรหัสออก โปรดดูคู่มือเรื่อง การรัน Apidog CLI ใน CI/CD pipeline ของคุณ หากคุณใช้ GitHub โดยเฉพาะ Apidog CLI ใน GitHub Actions มีเวิร์กโฟลว์ที่สามารถคัดลอกและวางได้
Lint ก่อน, ทดสอบทีหลัง ขั้นตอน lint รวดเร็วและจับปัญหาการออกแบบได้; ขั้นตอนการทดสอบจะช้ากว่าและจับปัญหาพฤติกรรมได้ รันทั้งสองขั้นตอนเป็นสองระยะ และ pull request จะต้องผ่านทั้งสองอย่าง
การเลือกและการนำชุดกฎมาใช้โดยปราศจากความเจ็บปวด
การเลือกเครื่องมือเป็นเรื่องง่าย การนำไปใช้กับ API ที่มีอยู่แล้วคือจุดที่ทีมหยุดชะงัก เพราะการรันครั้งแรกบนสเปกที่สมบูรณ์แล้วจะส่งคืนการละเมิดหลายร้อยรายการ และปฏิกิริยาที่ชัดเจนคือการปิดมันทั้งหมด
อย่าเริ่มจากกฎเป็นศูนย์และอย่าเริ่มจากทุกกฎในระดับ error เริ่มจากชุดกฎในตัว (spectral:oas) โดยตั้งค่าทุกสิ่งที่คุณเพิ่มเป็น warn รันมัน, อ่านจำนวน, และแก้ไขข้อผิดพลาดด้านความถูกต้องก่อน เพราะสิ่งเหล่านั้นคือบั๊กจริง จากนั้นเลือกกฎความสอดคล้องสองหรือสามข้อที่สำคัญที่สุดสำหรับลูกค้าของคุณ (โดยปกติคือ property casing และรูปแบบข้อผิดพลาดเดียว) และเลื่อนระดับเฉพาะสิ่งเหล่านั้นให้เป็น error ส่วนที่เหลือให้เป็น warning ทุกสปรินต์ ให้เลื่อนระดับ warning อีกหนึ่งหรือสองข้อให้เป็น error เมื่อ codebase ทันสมัยขึ้น ภายในหนึ่งไตรมาส ชุดกฎทั้งหมดจะถูกบังคับใช้ และไม่มีใครต้องหยุดการส่งมอบเพื่อไปถึงจุดนั้น
เขียนกฎสไตล์ภายในองค์กรอย่างประหยัด ทุกกฎที่กำหนดเองคือโค้ดที่ใครบางคนต้องบำรุงรักษาและอธิบายให้พนักงานใหม่ฟัง กฎจะได้รับตำแหน่งของมันก็ต่อเมื่อการละเมิดได้สร้างปัญหาให้คุณจริง ๆ ไม่ใช่เพราะมันอาจจะเกิดขึ้น สำหรับกฎที่คุณเขียน ให้พึ่งพาเลเยอร์การออกแบบเพื่อทำให้มันเกิดขึ้นได้ยาก: หากสคีมาของคุณถูกนำกลับมาใช้จากคำนิยามกลาง กฎ property-casing แทบจะไม่ทำงานเลยเพราะมีที่เดียวที่ชื่อถูกกำหนดไว้ กรอบแนวคิดว่ากฎใดที่ควรบังคับใช้ กับกฎใดที่ไม่จำเป็น ได้รับการครอบคลุมใน แนวทางปฏิบัติที่ดีที่สุดในการออกแบบ API
หากคุณออกแบบด้วยภาษาที่แตกต่างจาก YAML ดิบ linter ก็ยังคงใช้ได้ TypeSpec คอมไพล์ลงเป็น OpenAPI และคุณสามารถ lint เอกสารที่สร้างขึ้นได้ในลักษณะเดียวกัน; linter ไม่สนใจว่าไฟล์นั้นถูกเขียนขึ้นมาอย่างไร สนใจเพียงแค่ว่ามันระบุอะไร
Linter เข้ากับวงจรการออกแบบที่ใหญ่ขึ้นได้อย่างไร
linter เป็นหนึ่งในการควบคุมในเวิร์กโฟลว์ที่เน้นการออกแบบเป็นอันดับแรก ไม่ใช่ทั้งหมด วงจรทั้งหมดคือ: ออกแบบสัญญา, lint มัน, จำลองมันเพื่อให้ไคลเอ็นต์สามารถพัฒนาตามได้, ทดสอบการใช้งานจริงกับมัน, และเผยแพร่เอกสารจากมัน หากข้ามขั้นตอนใดขั้นตอนหนึ่ง ขั้นตอนอื่น ๆ ก็จะสูญเสียคุณค่า สเปกที่ผ่านการ lint แล้วแต่ไม่มีใครจำลอง ก็ยังคงบล็อกงานส่วนหน้า สเปกที่จำลองแล้วแต่ไม่มีใครทดสอบ ก็ยังคงแตกต่างจากความเป็นจริง
เหตุผลที่ต้องให้ความสำคัญกับการออกแบบเป็นอันดับแรกในวงจรนั้นเป็นเหตุผลเดียวกับที่ linting ได้ผล: ตรวจจับปัญหาในจุดที่แก้ไขได้ถูกที่สุด การเปลี่ยนชื่อคุณสมบัติในเครื่องมือออกแบบคือการแก้ไขเพียงครั้งเดียว การเปลี่ยนหลังจากสามทีมได้ส่งมอบโดยใช้ชื่อเดิมคือการย้ายระบบ linter บังคับใช้ความสอดคล้องกับไฟล์; กระบวนการที่เน้นการออกแบบเป็นอันดับแรกจะบังคับใช้กับข้อกำหนดก่อนที่ไฟล์จะถูกสร้างขึ้น หากคุณต้องการข้อโต้แย้งที่กว้างขึ้นสำหรับการจัดลำดับ API-first vs API design-first vs code-first จะแสดงข้อดีข้อเสีย และ เครื่องมือออกแบบ API แบบ contract-first ครอบคลุมเครื่องมือที่สนับสนุนสิ่งนี้
Apidog ครอบคลุมวงจรทั้งหมดในที่เดียว: ออกแบบด้วยสคีมาที่นำกลับมาใช้ใหม่ได้, จำลองได้ทันที, ทดสอบด้วย CLI ใน CI, และส่งออก OpenAPI ที่สะอาดสำหรับ linter ใด ๆ ที่คุณใช้เป็นมาตรฐาน linter ยังคงมีหน้าที่; เพียงแค่มีสิ่งให้มันตรวจจับน้อยลง
ปุ่ม