ציין מערך מיתרים כפרמטרי גוף בסוואגר
1. סקירה כללית
Swagger הוא קבוצת מפרטים לתיעוד ולתיאור ממשקי API של REST. הוא גם מספק ערכי דוגמה לפרמטרים של נקודות הקצה.
במדריך זה נראה כיצד לייצר ערך לדוגמה המוגדר כברירת מחדל חוּט מערכים, מכיוון שהתנהגות זו אינה מופעלת כברירת מחדל.
2. ציין מערך מיתרים כפרמטרים של גוף בסוואגר
הנושא מתעורר כאשר אנו רוצים לציין מערך של מיתרים כפרמטרים בגוף ב- Swagger.
ערך הדוגמה המוגדר כברירת מחדל של סוואגר הוא מעט אטום, כפי שניתן לראות בעורך סוואגר:
אז הנה אנו רואים שסוואגר לא ממש מראה דוגמה לאיך תוכן המערך צריך להראות. בואו נראה איך להוסיף אחד.
3. ימל
ראשית, אנו מתחילים לציין את מערך המיתרים ב- Swagger באמצעות סימון YAML. בחלק הסכימה אנו כוללים סוג: מערך עם פריטים מחרוזת.
כדי לתעד טוב יותר את ה- API ולהדריך את המשתמש, אנו יכולים להשתמש ב- דוגמא תווית כיצד להוסיף ערכים:
פרמטרים: - ב: תיאור גוף: "" חובה: שם אמיתי: סכימת שם: סוג: פריטי מערך: סוג: דוגמה למחרוזת: ["str1", "str2", "str3"]בואו נראה איך התצוגה שלנו אינפורמטיבית יותר:
4. ספרינגפוקס
לחלופין, אנו יכולים להשיג את אותה התוצאה באמצעות Springfox.
עלינו להשתמש ב- סוג מידע ו דוגמא במודל הנתונים עם @ApiModel ו @ApiModelProperty ביאורים:
@ApiModel בכיתה ציבורית Foo {מזהה פרטי ארוך; @ApiModelProperty (name = "name", dataType = "List", example = "[\" str1 \ ", \" str2 \ ", \" str3 \ "]") שם רשימה פרטי;לאחר מכן, עלינו גם להוסיף הערות ל בקר לתת לסוואגר להצביע על מודל הנתונים.
אז בואו נשתמש @ApiImplicitParams בשביל זה:
@RequestMapping (method = RequestMethod.POST, value = "/ foos") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiImplicitParams ({@ApiImplicitParam (name = "foo", value = "רשימת מיתרים", paramType = "body) ", dataType =" Foo ")}) Foo ציבורי ליצור (@RequestBody הסופי Foo foo) {וזה הכל!
5. מסקנה
בעת תיעוד ממשקי ה- API של REST, יתכן שיש לנו פרמטרים שהם מערכי מחרוזות. באופן אידיאלי, היינו מתעדים אותם עם ערכי דוגמה.
אנחנו יכולים לעשות זאת בסוואגר עם דוגמא תכונה. לחלופין, נוכל להשתמש ב- דוגמא מאפיין הערות ב- Springfox.
כמו תמיד, הקוד זמין ב- GitHub.
