streamalism.org

1. סקירה כללית

במדריך זה נלמד כיצד לעבוד איתו אובייקטים של JSON כפרמטרים של שאילתה באמצעות OpenAPI.

2. פרמטרי שאילתה ב- OpenAPI 2

OpenAPI 2 אינו תומך באובייקטים כפרמטרים של שאילתה; רק ערכים פרימיטיביים ומערכים של פרימיטיבים נתמכים.

מסיבה זו, במקום זאת נרצה להגדיר את פרמטר JSON שלנו כ- חוּט.

כדי לראות זאת בפעולה, בואו נגדיר פרמטר שנקרא פאראמים כ חוּט, למרות שננתח את זה כ- JSON בתקן האחורי שלנו:

swagger: "2.0" ... נתיבים: / tickets: get: tags: - סיכום "tickets": "שלח אובייקט JSON כפרמטר השאילתה" פרמטרים: - שם: "params" ב: "path" תיאור: "{ \ "סוג \": \ "foo \", \ "צבע \": \ "ירוק \"} "חובה: סוג אמיתי:" מחרוזת " 

כך, במקום:

קבל // localhost: 8080 / api / tickets? Type = foo & color = green

נעשה:

GET // localhost: 8080 / api / tickets? Params = {"type": "foo", "color": "green"}

3. שאילתות פאראמים ב- OpenAPI 3

OpenAPI 3 מציג תמיכה באובייקטים כפרמטרים של שאילתה.

כדי לציין פרמטר JSON, עלינו להוסיף a תוֹכֶן סעיף להגדרתנו הכולל את סוג MIME והסכמה:

openapi: 3.0.1 ... נתיבים: / tickets: get: tags: - סיכום כרטיסים: שלח אובייקט JSON כפרמטרים של שאילתת פרמטרים: - שם: params ב: תיאור השאילתה: '{"type": "foo", "color": "green"} 'חובה: schema true: type: מאפייני אובייקט: type: type: "string" color: type: "string" 

הבקשה שלנו יכולה להיראות כעת:

GET // localhost: 8080 / api / tickets? Params [type] = foo¶ms [color] = green

ובעצם זה עדיין יכול להיראות כמו:

GET // localhost: 8080 / api / tickets? Params = {"type": "foo", "color": "green"}

האפשרות הראשונה מאפשרת לנו להשתמש באימות פרמטרים, שיודיעו לנו אם משהו לא בסדר לפני הגשת הבקשה.

עם האפשרות השנייה, אנו סוחרים זאת בכדי לקבל שליטה רבה יותר על ה- backend כמו גם על תאימות OpenAPI 2.

4. קידוד כתובות אתרים

חשוב לציין כי בקבלת החלטה זו להעביר פרמטרים לבקשות כאובייקט JSON, נרצה לקודד את הפרמטר בכדי להבטיח תחבורה בטוחה.

אז לשלוח את כתובת האתר הבאה:

GET / tickets? Params = {"type": "foo", "color": "green"}

למעשה היינו עושים:

קבל / כרטיסים? Params =% 7B% 22 סוג% 22% 3A% 22 fooo% 22% 2C% 22 צבע% 22% 3 A% 22 ירוק% 22% 7 D

5. מגבלות

כמו כן, בואו נזכור את המגבלות של העברת אובייקט JSON כמכלול פרמטרים של שאילתה:

• ביטחון מופחת
• אורך מוגבל של הפרמטרים

לדוגמה, ככל שנציב יותר נתונים בפרמטר שאילתה, כך מופיע יותר ביומני השרת וב- ככל שהפוטנציאל לחשיפת נתונים רגישים גבוה יותר.

כמו כן, פרמטר שאילתה יחיד יכול לכלול לא יותר מ -2048 תווים. אין ספק שכולנו יכולים לדמיין תרחישים שבהם אובייקטים JSON שלנו גדולים מזה. באופן מעשי, קידוד URL של מחרוזת JSON שלנו למעשה יגביל אותנו לכ -1000 תווים עבור המטען שלנו.

דרך לעקיפת הבעיה היא לשלוח אובייקטים גדולים יותר של JSON בגוף. באופן זה אנו מתקנים את בעיית האבטחה וגם את מגבלת האורך של JSON.

בעצם, GET או POST תומכים בכך. סיבה אחת לשלוח גוף על GET היא לשמור על סמנטיקה RESTful של ה- API שלנו.

כמובן, זה קצת יוצא דופן ולא נתמך באופן אוניברסלי. לדוגמה, חלק מספריות ה- HTTP של JavaScript אינן מאפשרות לבקשות GET להיות בעלות בקשה.

בקיצור, בחירה זו היא פשרה בין סמנטיקה לתאימות אוניברסלית.

6. מסקנה

לסיכום, במאמר זה למדנו כיצד לציין אובייקטים של JSON כפרמטרים של שאילתה באמצעות OpenAPI. ואז ראינו כמה מההשלכות על ה- backend.

ההגדרות המלאות של OpenAPI עבור דוגמאות אלה זמינות ב- GitHub.