streamalism.org

רק הכרזתי על החדש למד אביב קורס, המתמקד ביסודות האביב 5 ומגף האביב 2:

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

תיעוד הוא חלק חיוני בבניית ממשקי API של REST. במדריך זה נבחן את SpringDoc - כלי שמפשט את הייצור והתחזוקה של מסמכי API, בהתבסס על מפרט OpenAPI 3, ליישומי Spring Boot 1.x ו- 2.x.

2. הגדרת springdoc-openapi

כדי ש- springdoc-openapi ייצור אוטומטית את מסמכי המפרט של OpenAPI 3 עבור ה- API שלנו, אנו פשוט מוסיפים את ה- springdoc-openapi-ui תלות שלנו pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

לאחר מכן, כאשר אנו מריצים את היישום שלנו, תיאורי OpenAPI יהיו זמינים בנתיב / v3 / api-docs כברירת מחדל - לדוגמא:

// localhost: 8080 / v3 / api-docs /

כדי להשתמש בנתיב מותאם אישית, אנו יכולים לציין ב application.properties קוֹבֶץ:

springdoc.api-docs.path = / api-docs

כעת נוכל לגשת למסמכים בכתובת:

// localhost: 8080 / api-docs /

הגדרות OpenAPI הן ב- JSONפורמט כברירת מחדל. ל יאמל בפורמט, נוכל להשיג את ההגדרות בכתובת:

//localhost:8080/api-docs.yaml

3. הגדרת springdoc-openapi עם ממשק המשתמש של Swagger

מלבד יצירת מפרט OpenAPI 3 עצמו, אנו יכולים לשלב את springdoc-openapi עם ממשק המשתמש של Swagger כך שנוכל לתקשר עם מפרט ה- API שלנו ולהפעיל את נקודות הקצה.

3.1. תלות של Maven

כל שעלינו לעשות כדי להגדיר את springdoc-openapi עם ממשק המשתמש של Swagger הוא להוסיף את התלות springdoc-openapi-ui לפרויקטים pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

כעת אנו יכולים לגשת לתיעוד ה- API בכתובת:

//localhost:8080/swagger-ui.html

3.2. תמיכה ל swagger-ui נכסים

Springdoc-openapi תומך גם במאפייני swagger-ui. אלה יכולים לשמש כמאפייני Spring Boot, עם הקידומת springdoc.swagger-ui.

לדוגמה, בואו נתאים אישית את הנתיב של תיעוד ה- API שלנו. אנו יכולים לעשות זאת על ידי שינוי שלנו application.properties לכלול:

springdoc.swagger-ui.path = / swagger-ui-custom.html

אז עכשיו תיעוד ה- API שלנו יהיה זמין בכתובת //localhost:8080/swagger-ui-custom.html.

כדוגמה נוספת, כדי למיין את נתיבי ה- API לפי שיטות ה- HTTP שלהם, אנו יכולים להוסיף:

springdoc.swagger-ui.operationsSorter = שיטה

3.3. ממשק API לדוגמא

נניח שליישום שלנו יש בקר לניהול סֵפֶרs:

@RestController @RequestMapping ("/ api / book") BookController בכיתה ציבורית {@ מאגר פרטי מאגר BookRepository; @GetMapping ("/ {id}") ספר ציבורי findById (@PathVariable מזהה ארוך) {return repository.findById (id) .orElseThrow (() -> BookNotFoundException חדש) ()); } @GetMapping ("/") findBooks אוסף ציבורי () {return repository.getBooks (); } @PutMapping ("/ {id}") @ ResponseStatus (HttpStatus.OK) עדכון ספר ציבורי ספר (@PathVariable ("id") סופי מחרוזת, @RequestBody ספר ספר סופי) {ספר חוזר; }} 

לאחר מכן, כאשר אנו מריצים את היישום שלנו, אנו יכולים להציג את התיעוד בכתובת:

//localhost:8080/swagger-ui-custom.html

בואו נקדוח אל ה / api / book נקודת קצה וראה את הפרטים לבקשתה ותגובתה:

4. שילוב של springdoc-openapi עם Spring WebFlux

אנו יכולים לשלב את springdoc-openapi ו- UI של Swagger בפרויקט Spring WebFlux על ידי הוספה springdoc-openapi-webflux-ui:

 org.springdoc springdoc-openapi-webflux-ui 1.5.2 

וכמו בעבר, ניתן יהיה לגשת למסמכים בכתובת:

//localhost:8080/swagger-ui.html

על מנת להתאים אישית את הנתיב, כאן שוב נוכל להוסיף את springdoc.swagger-ui.path נכס שלנו application.properties.

5. חשיפת מידע על עימוד

Spring Data JPA משתלב עם Spring MVC בצורה חלקה למדי. דוגמה אחת לשילובים כאלה היא תומכי תמיכה:

@GetMapping ("/ filter") עמוד ציבורי filterBooks (Pageable pageable) {return repository.getBooks (pageable); }

בהתחלה, אנו עשויים לצפות ש- SpringDoc תוסיף עמוד, גודל, ו סוג פרמטרי שאילתה לתיעוד שנוצר. עם זאת, כברירת מחדל, SpringDoc אינה עומדת בציפייה זו. על מנת לבטל את נעילת התכונה הזו, עלינו להוסיף את springdoc-openapi-data-rest תלות:

 org.springdoc springdoc-openapi-data-rest 1.5.2 

כעת הוא מוסיף את פרמטרי השאילתה הצפויים לתיעוד:

6. שימוש בתוסף springdoc-openapi Maven

ספריית springdoc-openapi מספקת תוסף Maven springdoc-openapi-maven-plugin ליצירת תיאורי OpenAPI ב ג'סון ו יאמל פורמטים.

ה springdoc-openapi-maven-plugin תוסף עובד עם אביב-מגף-עורב חיבור. מייבן מנהל את openapi תוסף במהלך מבחן האינטגרציה שלב.

בואו נראה כיצד נוכל להגדיר את התוסף שלנו pom.xml:

 org.springframework.boot spring-boot-maven-plugin 2.3.3.RELEASE pre-integration-test start post-integration-test stop org.springdoc springdoc-openapi-maven-plugin 0.2 אינטגרציה-מבחן ליצור 

כמו כן, אנו יכולים להגדיר את התוסף לשימוש בערכים מותאמים אישית:

  ......... // localhost: 8080 / v3 / api-docs openapi.json $ {project.build.directory} 

בואו נסתכל מקרוב על הפרמטרים שנוכל להגדיר עבור התוסף:

• apiDocsUrl - כתובת אתר שבה ניתן לגשת למסמכים בפורמט JSON, עם ברירת המחדל של // localhost: 8080 / v3 / api-docs
• שם קובץ פלט - שם הקובץ בו נשמרות ההגדרות, ברירת המחדל היא openapi.json
• outputDir - נתיב מוחלט עבור הספריה בה מאוחסנים המסמכים - כברירת מחדל, $ {project.build.directory}

7. הפקת מסמכים אוטומטית באמצעות אימות שעועית JSR-303

כאשר המודל שלנו כולל הערות אימות שעועית JSR-303, כגון @לא ריק, @NotBlank, @גודל, @Min, ו @ מקס, ספריית springdoc-openapi משתמשת בהם כדי ליצור תיעוד סכימה נוסף לאילוצים המתאימים.

בואו נראה דוגמה באמצעות שלנו סֵפֶר אפונה:

ספר בכיתה ציבורית {id ארוך פרטי; @NotBlank @Size (min = 0, max = 20) כותרת מחרוזת פרטית; @NotBlank @Size (min = 0, max = 30) מחבר מחרוזת פרטי; }

כעת, התיעוד שנוצר עבור ה- סֵפֶר שעועית היא קצת יותר אינפורמטיבית:

8. צור תיעוד באמצעות @ControllerAdvice ו @ תגובה סטטוס

באמצעות @ תגובה סטטוס על שיטות ב @ RestControllerAdvice class ייצור תיעוד אוטומטי עבור קודי התגובה. בזה @ RestControllerAdvice בכיתה, שתי השיטות מתוארות באמצעות @ תגובה סטטוס:

מחלקה ציבורית @RestControllerAdvice GlobalControllerExceptionHandler {@ExceptionHandler (ConversionFailedException.class) @ResponseStatus (HttpStatus.BAD_REQUEST) ResponseEntity public handlingConnversion (RuntimeException ex) {להחזיר ResponseEntity חדש (ex.getBess_Start; } @ExceptionHandler (BookNotFoundException.class) @ResponseStatus (HttpStatus.NOT_FOUND) ידית תגובה תגובה ציבורית PublicNotFound (RuntimeException ex) {להחזיר ResponseEntity חדש (ex.getMessage (), HttpStatus.NOT_FOUND); }}

כתוצאה מכך, כעת אנו יכולים לראות את התיעוד של קודי התגובה 400 ו- 404:

9. צור תיעוד באמצעות @מבצע ו @ApiResponses

לאחר מכן, בואו נראה כיצד נוכל להוסיף תיאור כלשהו ל- API שלנו באמצעות כמה הערות ספציפיות ל- OpenAPI.

על מנת לעשות זאת, נרשום על הבקר שלנו / api / book / {id} נקודת סיום עם @מבצע ו @ApiResponses:

@Operation (סיכום = "קבל ספר לפי המזהה שלו") @ApiResponses (value = {@ApiResponse (responseCode = "200", description = "מצא את הספר", content = {@Content (mediaType = "application / json") , סכמה = @Schema (יישום = Book.class))}), @ApiResponse (responseCode = "400", תיאור = "מסופק מזהה לא חוקי", content = @Content), @ApiResponse (responseCode = "404", תיאור = "הספר לא נמצא", content = @Content)}) @ GetMapping ("/ {id}") public book findById (@Parameter (תיאור = "מזהה הספר שיש לחפש") @PathVariable מזהה ארוך) {מאגר החזרה. findById (id) .orElseThrow (() -> BookNotFoundException חדש ()); }

והנה ההשפעה:

כפי שאנו רואים, הטקסט שהוספנו אליו @מבצע ממוקם ברמת פעולת ה- API. באופן דומה, התיאור נוסף על שונים @ApiResponse אלמנטים ב @ApiResponses הערת מכולה נראית גם כאן ומוסיפה משמעות לתגובות ה- API שלנו.

ככל הנראה, איננו מקבלים שום סכמה לתגובות 400 ו- 404 לעיל. כי הגדרנו ריק @תוֹכֶן עבורם, רק התיאורים שלהם מוצגים.

10. תמיכה בקוטלין

מאז Spring Boot 2.x יש תמיכה מהשורה הראשונה בקוטלין, SpringDoc תומך בשפת JVM זו מהקופסה ליישומי Boot 2.x.

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

לאחר ההתקנה הראשונית, נוסיף מחלקת נתונים ובקר. נוסיף אותם בחבילת משנה של אפליקציית האתחול שלנו, כך שכאשר היא מופעלת, היא תבחר את שלנו FooController יחד עם הקודם BookController:

מחלקת נתונים של @Entity Foo (@ id id id: Long = 0, @NotBlank @Size (min = 0, max = 50) name val: String = "") @RestController @RequestMapping ("/") class FooController () { val fooList: List = listOf (Foo (1, "one"), Foo (2, "two")) @Operation (סיכום = "קבל את כל foos") @ApiResponses (value = [ApiResponse (responseCode = "200", תיאור = "נמצא Foos", content = [(Content (mediaType = "application / json", array = (ArraySchema (schema = Schema (implementation = Foo :: class))))]), ApiResponse (responseCode = "400 ", תיאור =" בקשה רעה ", content = [Content ()]), ApiResponse (responseCode =" 404 ", description =" לא מצא שום Foos ", content = [Content ()])]) @ GetMapping (" / foo ") כיף getAllFoos (): רשימה = fooList}

כעת כאשר אנו פוגעים בכתובת ה- URL של תיעוד ה- API, נראה את ה- פו ממשק API גם:

כדי לשפר את התמיכה בסוגי Kotlin, אנו יכולים להוסיף תלות זו:

 org.springdoc springdoc-openapi-kotlin

לאחר מכן, סכימת ה- Foo שלנו תיראה אינפורמטיבית יותר. דומה לזה שהיה כשהוספנו אימות שעועית JSR-303:

11. מסקנה

במאמר זה למדנו להקים את springdoc-openapi בפרויקטים שלנו. ואז ראינו כיצד לשלב את springdoc-openapi עם ממשק המשתמש של Swagger. ראינו גם כיצד לעשות זאת בפרויקטים של Spring Webflux.

לאחר מכן, השתמשנו בתוסף springdoc-openapi Maven כדי ליצור הגדרות OpenAPI עבור ממשקי ה- API שלנו, וראינו כיצד לחשוף מידע בנושא החלפה ומיון מ- Spring Data. לאחר מכן, בדקנו כיצד springdoc-openapi מייצר תיעוד באופן אוטומטי באמצעות הערות אימות שעועית JSR 303 ואת @ תגובה סטטוס ביאורים ב @ControllerAdvice מעמד.

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

Springdoc-openapi מייצר תיעוד API לפי מפרט OpenAPI 3. יתר על כן, הוא גם מטפל בתצורת ממשק המשתמש של Swagger עבורנו, מה שהופך את יצירת מסמכי ה- API למשימה די פשוטה.

כמו תמיד, הקוד זמין ב- GitHub.

רק הכרזתי על החדש למד אביב קורס, המתמקד ביסודות האביב 5 ומגף האביב 2: