streamalism.org

Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak:

1. Áttekintés

A tavaszi REST Docs pontos és olvasható dokumentációt generál a RESTful szolgáltatásokhoz. Kombinálja a kézzel írt dokumentációt a Spring tesztekkel készített, automatikusan létrehozott dokumentumrészletekkel.

2. Előnyök

A projekt egyik fő filozófiája a tesztek használata a dokumentáció elkészítéséhez. Ez biztosítja, hogy a létrehozott dokumentáció mindig pontosan megfeleljen az API tényleges viselkedésének. Ezenkívül a kimenetet készen áll az Asciidoctor, az AsciiDoc szintaxisa köré összpontosító kiadói eszközlánc feldolgozására. Ez ugyanaz az eszköz, amelyet a Spring Framework dokumentációjának létrehozásához használnak.

Ezek a megközelítések csökkentik az egyéb keretek által előírt korlátozásokat. A Spring REST Docs pontos, tömör és jól felépített dokumentációt készít. Ez a dokumentáció lehetővé teszi, hogy a webszolgáltatás fogyasztói minimális felhajtás mellett megszerezzék a szükséges információkat.

Az eszköznek van néhány egyéb előnye, például:

• göndör és http kérelem részleteket generál
• könnyen csomagolható dokumentáció a projektek jar fájljába
• könnyen hozzáadhat további információkat a kivonatokhoz
• támogatja a JSON-t és az XML-t is

A kivonatokat előállító tesztek a Spring MVC Test támogatás, a Spring Webflux segítségével írhatók WebTestClient vagy REST-biztosított.

Példáinkban a Spring MVC teszteket fogjuk használni, de a többi keretrendszer használata nagyon hasonló.

3. Függőségek

A Spring REST Docs projektben való használatának ideális módja egy függőségkezelő rendszer használata. Itt a Maven-t használjuk felépítési eszközként, így az alábbi függőség átmásolható és beilleszthető a POM-ba:

 org.springframework.restdocs spring-restdocs-mockmvc 2.0.4. KÖZLEMÉNY 

A függőség új verzióját itt is ellenőrizheti.

Példánkban szükségünk van a tavasz-restdocs-mockmvc függőség, mivel tesztjeink létrehozásához a Spring MVC teszt támogatást használjuk.

Ha teszteket akarunk írni a WebTestClient vagy a REST Assured használatával, akkor szükségünk lesz a tavaszi-restdocs-webtestclient és a rugó-restdocs-restassured függőségekre.

4. Konfiguráció

Mint említettük, a Spring MVC Test keretrendszert fogjuk használni a REST szolgáltatásokkal kapcsolatos kérések benyújtásához, amelyeket dokumentálni kell. A teszt futtatása dokumentációs részleteket állít elő a kéréshez és az ebből adódó válaszhoz.

A könyvtárat mind a JUnit 4, mind a JUnit 5 tesztekkel használhatjuk. Nézzük meg az egyes konfigurációkat.

4.1. JUnit 4 konfiguráció

A JUnit 4 tesztek dokumentációs kivonatainak előállításának legelső lépése a nyilvánosságot hirdet JUnitRestDocumentation mező, amelyet JUnit-ként jegyeznek fel @Szabály.

A JUnitRestDocumentation A szabály azzal a kimeneti könyvtárral van konfigurálva, amelybe a létrehozott kódrészleteket el kell menteni. Ez a könyvtár lehet például a Maven kiépítési könyvtár:

@Rule public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation ("target / generated-snippets");

Ezután beállítottuk a MockMvc kontextusban, hogy konfigurálva legyen dokumentáció készítésére:

@Autowired private WebApplicationContext kontextus; privát MockMvc mockMvc; @ Mielőtt nyilvános void setUp () {this.mockMvc = MockMvcBuilders.webAppContextSetup (this.context) .apply (dokumentációKonfiguráció (this.restDocumentation)) .build (); }

A MockMvc az objektum konfigurálása egy MockMvc használatávalRestDocumentationConfigurer. Ennek az osztálynak a példánya beszerezhető a statikusból dokumentáció: Konfiguráció () módszer be org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.

4.2. 5. JUnit konfiguráció

A JUnit 5 teszt használatához ki kell terjesztenünk a tesztet a RestDocumentationExtension osztály:

@ExtendWith ({RestDocumentationExtension.class, SpringExtension.class}) @SpringBootTest nyilvános osztály ApiDocumentationJUnit5IntegrationTest {// ...}

Ez az osztály automatikusan a / target / generated-snippets kimeneti könyvtár a Maven használatakor, vagy / build / generál-kivonatok Gradle számára.

Ezután fel kell állítanunk a MockMvc például egy @BeforeEach módszer:

@BeforeEach public void setUp (WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {this.mockMvc = MockMvcBuilders.webAppContextSetup (webApplicationContext) .apply (dokumentációConfiguration) (restDoc) }

Ha nem a JUnit-et használjuk a tesztekhez, akkor a ManualRestDocumentation osztály.

5. Pihenő szolgáltatás

Hozzunk létre egy CRUD RESTful szolgáltatást, amelyet dokumentálhatunk:

@RestController @RequestMapping ("/ crud") public class CRUDController {@GetMapping public List read (@RequestBody CrudInput crudInput) {List returnList = new ArrayList (); returnList.add (crudInput); return returnList; } @ResponseStatus (HttpStatus.CREATED) @PostMapping public HttpHeaders save (@RequestBody CrudInput crudInput) {HttpHeaders httpHeaders = new HttpHeaders (); httpHeaders.setLocation (linkTo (CRUDController.class) .slash (crudInput.getTitle ()). toUri ()); visszatér httpHeaders; } @DeleteMapping ("/ {id}") public void delete (@PathVariable ("id") long id) {// törlés}}

Ezután tegyünk hozzá egy IndexController amely egy oldalt ad vissza a linkre a CRUD vezérlő alapvégpont:

@RestController @RequestMapping ("/") public class IndexController {static class CustomRepresentationModel extends RepresentationModel {public CustomRepresentationModel (Link initialLink) {super (initialLink); }} @GetMapping public CustomRepresentationModel index () {return new CustomRepresentationModel (linkTo (CRUDController.class) .withRel ("crud")); }}

6. JUnit tesztek

Visszatérve a tesztekre, használhatjuk a MockMvc például, hogy felhívjuk szolgáltatásainkat, és dokumentáljuk a kérést és a választ.

Első, hogy megbizonyosodjon mindenről MockMvc a hívás automatikusan dokumentálódik minden további konfiguráció nélkül, használhatjuk a alwaysDo () módszer:

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

Ez a beállítás biztosítja, hogy mindenki mindenkinek MockMvc hívás esetén az alapértelmezett kivonatok a tesztmódszer nevét tartalmazó mappában jönnek létre. Továbbá a prettyPrint () az előfeldolgozó könnyebben olvasható módon jeleníti meg a kivonatokat.

Folytassuk néhány hívásunk testreszabását.

A hivatkozást tartalmazó indexoldalunk dokumentálásához használhatjuk a statikusat linkek () módszer:

A @Test public void indexExample () dobja a Kivételt {this.mockMvc.perform (get ("/")). AndExpect (status (). IsOk ()) .andDo (document ("index", links (linkWithRel ("crud") ) .description ("A CRUD erőforrás")), responseFields (subsectionWithPath ("_ links") .description ("Linkek más forrásokhoz")) responseHeaders (headerWithName ("Content-Type") .description ("The Content-Type of a hasznos teher ")))); }

Itt használjuk a linkWithRel () módszer a hivatkozás dokumentálására / nyers.

Hozzáadni a Tartalom típus fejléc a válaszhoz, amelyet a headerWithName () metódus és hozzáadás a responseHeaders () módszer.

A válasz hasznos terhelését a responseFields () módszer. Ezt fel lehet használni a válasz bonyolultabb alszakaszának vagy egyetlen mező dokumentálásához az subsectionWithPath () vagy fieldWithPath () módszerekkel.

A válasz hasznos terheléséhez hasonlóan segítségével is dokumentálhatjuk a kérelem hasznos terhelését requestPayload ():

@Test public void crudCreateExample () dobja a Kivételt {Map crud = new HashMap (); crud.put ("cím", "Minta modell"); crud.put ("body", "//www.baeldung.com/"); this.mockMvc.perform (post ("/ crud"). contentType (MediaTypes.HAL_JSON) .content (this.objectMapper.writeValueAsString (crud))) .andExpect (status (). isCreated ()) .andDo (dokumentum (" create-crud-example ", requestFields (fieldWithPath (" id "). description (" A bemenet azonosítója "), fieldWithPath (" title "). leírás (" A bemenet címe "), fieldWithPath (" body " ) .leírás ("A bemenet törzse"),)))); }

Ebben a példában dokumentáltuk a POST kérelmünket, amely a CrudInput modell címsorral és törzsmezőkkel, és CREATED állapotot küld. Minden mezőt a fieldWithPath () módszer.

A kérelem és az elérési út paraméterének dokumentálásához használhatjuk a requestParameters () és pathParameters () mód. Mindkét módszer a paraméterWithName () módszer az egyes paraméterek leírására:

A @Test public void crudDeleteExample () dobja a Kivételt {this.mockMvc.perform (delete ("/ crud / {id}", 10)). AndExpect (status (). IsOk ()) .andDo (document ("crud-delete) -example ", pathParameters (paraméterWithName (" id "). leírás (" A törlendő bemenet azonosítója "))); }

Itt dokumentáltuk a törlés végpontunkat, amely egy id elérési út paraméter.

A tavaszi REST Docs projekt még erőteljesebb dokumentációs funkciókat tartalmaz, mint például a terepi korlátozások és a dokumentációban megtalálható kérési részek.

7. Kimenet

Amint a build sikeresen fut, a REST docs kivonatok kimenete létrejön, és a rendszer elmenti őket target / generált-kivonatok mappa:

A létrehozott kimenet tartalmazza a szolgáltatással kapcsolatos információkat, a REST szolgáltatás hívását, például a „curl” hívásokat, a HTTP kérést és a REST szolgáltatás válaszát, valamint a szolgáltatásra mutató linkeket / végpontokat:

CURL parancs

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

HTTP - REST válasz

[forrás, http, options = "nowrap"] ---- HTTP / 1.1 200 OK Tartalom-típus: application / hal + json; charset = UTF-8 Tartalom-hossz: 93 {"_links": {"crud": {"href": "// localhost: 8080 / crud"}}} ----

8. Részletek használata dokumentáció készítéséhez

A töredékek nagyobb dokumentumban történő használatához hivatkozhat rájuk az Asciidoc segítségével magába foglalja. Esetünkben dokumentumot hoztunk létre src / docs hívott api-útmutató.adoc:

Abban a dokumentumban, ha hivatkozni akartunk a linkek kódrészletére, helyőrzővel felvehetjük {részletek} amelyet Maven váltja fel, amikor feldolgozza a dokumentumot:

==== A linkek tartalmazzák a következőt: :: {kivonatok} /index-example/linkek.adoc []

9. Asciidocs Maven beépülő modulok

Az Asciidoc API-útmutatójának olvasható formátumba konvertálásához hozzáadhatunk egy Maven plugint a build életciklusához. Ennek engedélyezéséhez több lépés van:

1. Alkalmazza az Asciidoctor plugint a pom.xml
2. Adjon hozzá egy függőséget tavasz-restdocs-mockmvc ban,-ben testCompile konfiguráció a függőségek szakaszban említett módon
3. Konfiguráljon egy tulajdonságot a létrehozott kivonatok kimeneti helyének meghatározásához
4. Konfigurálja a teszt feladat a kivonatok könyvtárának hozzáadásához kimenetként
5. Konfigurálja a asciidoctor feladat
6. Adjon meg egy nevű attribútumot részleteket amelyek akkor használhatók, ha a létrehozott részleteket felveszik a dokumentációba
7. Tegye függővé a feladatot a teszt feladatot, hogy a tesztek a dokumentáció létrehozása előtt fussanak
8. Konfigurálja a részleteket könyvtár bemenetként. Az összes létrehozott kivonat ebben a könyvtárban jön létre

Adja hozzá a kódrészlet könyvtárat tulajdonságként a pom.xml így az Asciidoctor beépülő modul ezt az elérési utat használhatja a kódrészletek létrehozásához ebben a mappában:

 $ {project.build.directory} / generált kivonatok 

A Maven plugin konfigurációja a pom.xml az Asciidoc kódrészletek létrehozása a buildből az alábbiak szerint történik:

 org.asciidoctor asciidoctor-maven-plugin 1.5.6 generator-docs csomag process-asciidoc html könyv $ {snippetsDirectory} src / docs / asciidocs target / generált-docs 

10. API Doc Generation folyamat

Amikor a Maven összeállítás fut és a tesztek végrehajtásra kerülnek, az összes kivonatot a konfigurált kódrészlet mappában generálja target / generált-kivonatok Könyvtár. A kivonatok létrehozása után a készítési folyamat HTML kimenetet generál.

A létrehozott HTML fájl formázott és olvasható, így a REST dokumentáció használatra kész. A Maven build futtatásakor a dokumentumok a legújabb frissítésekkel is elkészülnek.

11. Következtetés

A dokumentáció hiánya jobb, mint a hibás dokumentáció, de a Spring REST dokumentumok segítenek pontos dokumentáció készítésében a RESTful szolgáltatásokhoz.

Hivatalos tavaszi projektként három tesztkönyvtár használatával éri el céljait: Spring MVC Test, WebTestClient és Pihenés biztosított. A dokumentáció előállításának ez a módszere segíthet a RESTful API-k fejlesztésének és dokumentálásának tesztvezérelt megközelítésében.

A cikk alapján talál egy példaprojektet a hivatkozott GitHub-tárházban.

Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak: