מבוא למסמכי REST באביב

REST למעלה

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

>> בדוק את הקורס

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

Spring REST Docs מייצר תיעוד עבור שירותי RESTful שהוא מדויק וקריא כאחד. הוא משלב תיעוד בכתב יד עם קטעי מסמכים שנוצרו אוטומטית המיוצרים עם מבחני אביב.

2. יתרונות

אחת הפילוסופיות העיקריות שעומדות מאחורי הפרויקט היא שימוש במבחנים להפקת התיעוד. זה מבטיח שהתיעוד שנוצר תמיד תואם באופן מדויק להתנהגות הממשית של ה- API. בנוסף, הפלט מוכן לעיבוד על ידי Asciidoctor, שרשרת כלים לפרסום שבמרכזה התחביר AsciiDoc. זהו אותו כלי המשמש להפקת התיעוד של Spring Framework.

גישות אלה מקטינות את המגבלות שמטילים מסגרות אחרות. Spring REST Docs מייצר תיעוד מדויק, תמציתי ובנוי היטב. תיעוד זה מאפשר לצרכני שירותי האינטרנט לקבל את המידע הדרוש להם במינימום מהומה.

לכלי יש כמה יתרונות אחרים, כמו:

  • נוצרים קטעי בקשה לתלתל ו- http
  • קל לארוז תיעוד בקובץ jar
  • קל להוסיף מידע נוסף לקטעים
  • תומך גם ב- JSON וגם ב- XML

ניתן לכתוב את המבחנים המייצרים את התוספים באמצעות תמיכת Spring MVC Test, Spring Webflux WebTestClient או מבטיח מנוחה.

בדוגמאות שלנו נשתמש במבחני MVC באביב, אך השימוש במסגרות האחרות דומה מאוד.

3. תלות

הדרך האידיאלית להתחיל להשתמש ב- Spring REST Docs בפרויקט היא באמצעות מערכת ניהול תלות. כאן אנו משתמשים ב- Maven ככלי לבנייה, כך שניתן להעתיק ולהדביק את התלות למטה לתוך ה- POM שלך:

 org.springframework.restdocs spring-restdocs-mockmvc 2.0.4.RELEASE 

אתה יכול גם לבדוק ב- Maven Central גרסה חדשה של התלות כאן.

בדוגמה שלנו, אנו זקוקים ל spring-restdocs-mockmvc תלות מכיוון שאנו משתמשים בתמיכת מבחני MVC באביב כדי ליצור את הבדיקות שלנו.

אם אנו רוצים לכתוב בדיקות באמצעות WebTestClient או REST מובטח, נזדקק לתלות האביב-restdocs-webtestclient ו- spring-restdocs-restassured.

4. תצורה

כאמור, נשתמש במסגרת Spring MVC Test לבקשות לשירותי REST המתועדים. הפעלת הבדיקה מייצרת קטעי תיעוד לבקשה ולתגובה המתקבלת.

אנו יכולים להשתמש בספרייה עם מבחני JUnit 4 ו- JUnit 5. בואו נראה את התצורה הדרושה לכל אחד.

4.1. תצורת JUnit 4

השלב הראשון ביצירת קטעי תיעוד למבחני JUnit 4 הוא לבצע להכריז על ציבור JUnitRestDocumentation שדה המסומן כ- JUnit @כְּלָל.

ה JUnitRestDocumentation הכלל מוגדר עם ספריית הפלט אליה יש לשמור את קטעי הטקסט שנוצרו. לדוגמא, ספרייה זו יכולה להיות ספריית ה- Build-out של Maven:

@ כלל JUnitRestDocumentation ציבורי restDocumentation = JUnitRestDocumentation חדש ("יעד / שנוצר קטעי טקסט");

לאחר מכן, הקמנו את MockMvc הקשר כך שיוגדר לייצר תיעוד:

@Autowired פרטי WebApplicationContext; פרטי MockMvc mockMvc; @ לפני setUp הריק הציבורי () {this.mockMvc = MockMvcBuilders.webAppContextSetup (this.context) .apply (documentationConfiguration (this.restDocumentation)) .build (); }

ה MockMvc האובייקט מוגדר באמצעות MockMvcRestDocumentationConfigurer. מופע של מעמד זה ניתן להשיג מהסטטי documentConfiguration () שיטה ב org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.

4.2. תצורת JUnit 5

כדי לעבוד עם מבחן JUnit 5, עלינו להאריך את הבדיקה עם ה- RestDocumentationExtension מעמד:

@ExtendWith ({RestDocumentationExtension.class, SpringExtension.class}) @SpringBootTest מחלקה ציבורית ApiDocumentationJUnit5IntegrationTest {// ...}

מחלקה זו מוגדרת אוטומטית עם / target / שנוצר-קטעים ספריית הפלט בעת שימוש ב- Maven, או / לבנות / ליצור-קטעים עבור גרדל.

לאחר מכן, עלינו להגדיר את ה- MockMvc מופע ב @ לפני כל אחד שיטה:

@ לפני כל SetUp הריק הציבורי (WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {this.mockMvc = MockMvcBuilders.webAppContextSetup (webApplicationContext) .apply (documentConfiguration (restDocumentation)). }

אם איננו משתמשים ב- JUnit למבחנים, עלינו להשתמש ב- ManualRestDocumentation מעמד.

5. שירות נח

בואו ניצור שירות CRUD RESTful שנוכל לתעד:

@RestController @RequestMapping ("/ crud") מחלקה ציבורית CRUDController {@GetMapping רשימה ציבורית נקרא (@RequestBody CrudInput crudInput) {List returnList = new ArrayList (); returnList.add (crudInput); להחזיר returnList; } @ תגובה סטטוס (HttpStatus. CREATED) @ פוסט מיפוי HttpHeaders הציבור שמור (@RequestBody CrudInput crudInput) {HttpHeaders httpHeaders = HttpHeaders חדש (); httpHeaders.setLocation (linkTo (CRUDController.class) .slash (crudInput.getTitle ()). toUri ()); החזר httpHeaders; } @DeleteMapping ("/ {id}") מחיקה בטלנית ציבורית (@PathVariable ("id") מזהה ארוך) {// delete}}

ואז, בואו נוסיף גם IndexController שמחזיר דף עם קישור ל- CRUD בקר נקודת סיום בסיסית:

@RestController @RequestMapping ("/") מחלקה ציבורית IndexController {מחלקה סטטית CustomRepresentationModel מרחיב RepresentationModel {public CustomRepresentationModel (קישור initialLink) {super (initialLink); }} @ GetMapping אינדקס CustomRepresentationModel ציבורי () {להחזיר CustomRepresentationModel חדש (linkTo (CRUDController.class). WithRel ("crud")); }}

6. מבחני JUnit

בחזרה למבחנים נוכל להשתמש ב- MockMvc למשל להתקשר לשירותים שלנו ולתעד את הבקשה והתגובה.

ראשון, כדי לוודא כל MockMvc שיחה מתועדת אוטומטית ללא כל תצורה נוספת שנוכל להשתמש בה תמיד לעשות () שיטה:

this.mockMvc = MockMvcBuilders // ... .alwaysDo (document ("{method-name}", preprocessRequest (prettyPrint ()), preprocessResponse (prettyPrint ()))) .build ();

הגדרה זו מבטיחה כי כל אחד לכולם MockMvc להתקשר, קטעי ברירת המחדל נוצרים בתיקיה עם שם שיטת הבדיקה. כמו כן, החלת ה- prettyPrint () מעבד מראש מציג את התוספים בצורה קריאה יותר.

בואו נמשיך בהתאמה אישית של כמה מהשיחות שלנו.

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

@Test public void indexExample () זורק Exception {this.mockMvc.perform (get ("/")). AndExpect (status (). IsOk ()) .andDo (document ("index", links (linkWithRel ("crud") ) .description ("משאב CRUD")), responseFields (subsectionWithPath ("_ קישורים") .description ("קישורים למשאבים אחרים")) responseHeaders (headerWithName ("סוג תוכן") .description ("סוג התוכן של המטען ")))); }

הנה, אנו משתמשים ב- linkWithRel () שיטה לתעד קישור אל / גס.

כדי להוסיף א סוג תוכן כותרת לתגובה שאנו מתעדים אותה באמצעות headerWithName () שיטה והוספת אותו ל responseHeaders () שיטה.

אנו מתעדים גם את מטען התגובה באמצעות ה- responseFields () שיטה. זה יכול לשמש לתיעוד תת-סעיף מורכב יותר של התגובה או שדה בודד בשיטות subsectionWithPath () או fieldWithPath ().

בדומה למטען התגובה, אנו יכולים גם לתעד את מטען המטען הבקשה באמצעות requestPayload ():

@Test ציבורי בטל crudCreateExample () זורק חריג {Map crud = חדש HashMap (); crud.put ("כותרת", "מודל לדוגמא"); crud.put ("גוף", "//www.baeldung.com/"); this.mockMvc.perform (post ("/ crud"). contentType (MediaTypes.HAL_JSON) .content (this.objectMapper.writeValueAsString (crud))). andExpect (status (). isCreated ()) .andDo (document (") create-crud-example ", requestFields (fieldWithPath (" id "). תיאור (" מזהה הקלט "), fieldWithPath (" title "). תיאור (" כותרת הקלט "), fieldWithPath (" body " ). תיאור ("גוף הקלט"),)))); }

בדוגמה זו תיעדנו את בקשת ה- POST שלנו המקבלת CrudInput מודל עם שדות כותרת וגוף ושולח סטטוס CREATED. כל שדה מתועד באמצעות fieldWithPath () שיטה.

כדי לתעד פרמטר של בקשה ונתיב, נוכל להשתמש ב- requestParameters () ו pathParameters () שיטות. בשתי השיטות משתמשים בא parameterWithName () שיטה לתאר כל פרמטר:

@Test ציבורי בטל crudDeleteExample () זורק חריג {this.mockMvc.perform (מחק ("/ crud / {id}", 10)). ו- Expect (status (). IsOk ()). AndDo (document ("crud-delete) -דוגמא ", pathParameters (parameterWithName (" id "). תיאור (" מזהה הקלט למחיקה ")))); }

כאן תיעדנו את נקודת הקצה למחוק שלנו שמקבלת תְעוּדַת זֶהוּת פרמטר נתיב.

פרויקט Spring REST Docs מכיל פונקציות תיעוד חזקות עוד יותר, כגון מגבלות שדה וחלקי בקשה שניתן למצוא בתיעוד.

7. פלט

לאחר שהבנייה פועלת בהצלחה, הפלט של קטעי המסמכים REST ייווצר ויישמר ב- יעד / קטעי שנוצר תיקיה:

בפלט שנוצר יהיה מידע על השירות, כיצד להתקשר לשירות REST כמו שיחות 'תלתל', בקשת HTTP ותגובה משירות REST וקישורים / נקודות קצה לשירות:

פיקוד CURL

---- $ curl '// localhost: 8080 /' -i ----

תגובת HTTP - REST

[source, http, options = "nowrap"] ---- HTTP / 1.1 200 OK תוכן סוג: יישום / hal + json; charset = UTF-8 אורך תוכן: 93 {"_links": {"crud": {"href": "// localhost: 8080 / crud"}}} ----

8. שימוש בקטעים ליצירת תיעוד

כדי להשתמש בתוספים במסמך גדול יותר, אתה יכול להפנות אליהם באמצעות Asciidoc כולל. במקרה שלנו, יצרנו מסמך ב- src / docs שקוראים לו api-guide.adoc:

במסמך זה, אם ברצוננו להפנות לקטע הקישורים, אנו יכולים לכלול אותו באמצעות מציין מיקום {קטעים} שיוחלף על ידי Maven כאשר הוא מעבד את המסמך:

==== קישורים כוללים :: {snippets} / index-example/links.adoc []

9. תוספים של Asciidocs Maven

כדי להמיר את מדריך ה- API מ- Asciidoc לפורמט קריא, אנו יכולים להוסיף תוסף Maven למחזור החיים של ה- build. ישנם מספר שלבים כדי לאפשר זאת:

  1. החל את תוסף Asciidoctor על ה- pom.xml
  2. הוסף תלות ב- spring-restdocs-mockmvc בתוך ה testCompile תצורה כאמור בסעיף תלות
  3. קבע תצורה של מאפיין כדי להגדיר את מיקום הפלט עבור קטעי מידע שנוצרו
  4. הגדר את מִבְחָן המשימה להוסיף את ספריית התמציות כפלט
  5. הגדר את asciidoctor מְשִׁימָה
  6. הגדר מאפיין בשם קטעים שניתן להשתמש בהם כשכלול את קטעי הטקסט שנוצרו בתיעוד שלך
  7. הפוך את המשימה לתלוי ב- מִבְחָן המשימה כך שהבדיקות יופעלו לפני יצירת התיעוד
  8. הגדר את קטעים ספריה כקלט. כל קטעי הטקסט שנוצרו ייווצרו בספריה זו

הוסף את ספריית התמציות כמאפיין ב- pom.xml כך שתוסף Asciidoctor יכול להשתמש בנתיב זה כדי ליצור קטעי מידע תחת תיקיה זו:

 $ {project.build.directory} / generated-snippets 

תצורת התוסף Maven ב pom.xml להפיק את קטעי Asciidoc מהבניין הוא להלן:

 org.asciidoctor asciidoctor-maven-plugin 1.5.6 תהליך החבילה של docs-asciidoc html book $ {snippetsDirectory} src / docs / asciidocs target / generated-docs 

10. תהליך יצירת מסמכי API

כאשר ה- Maven build פועל והבדיקות מבוצעות, כל התוספים ייווצרו בתיקיית Snippets תחת התצורה המוגדרת יעד / קטעי שנוצר מַדרִיך. לאחר יצירת הטקסטים, תהליך הבנייה מייצר פלט HTML.

קובץ ה- HTML שנוצר מעוצב וקריא, כך שתיעוד ה- REST מוכן לשימוש. בכל פעם שבניית Maven פועלת, המסמכים נוצרים גם עם העדכונים האחרונים.

11. מסקנה

אין תיעוד טוב יותר מתיעוד שגוי, אך מסמכי REST של Spring יעזרו לייצר תיעוד מדויק עבור שירותי RESTful.

כפרויקט אביב רשמי, הוא משיג את יעדיו באמצעות שלוש ספריות מבחן: מבחן MVC באביב, WebTestClient ותנוח לנוח. שיטה זו ליצירת תיעוד יכולה לסייע בתמיכה בגישה מונחית-מבחן לפיתוח ותיעוד ממשקי API של RESTful.

תוכל למצוא פרויקט לדוגמה המבוסס על הקוד במאמר זה במאגר GitHub המקושר.

REST תחתון

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

>> בדוק את הקורס

$config[zx-auto] not found$config[zx-overlay] not found