streamalism.org

Upravo sam najavio novo Uči proljeće tečaj, usredotočen na osnove Spring 5 i Spring Boot 2:

1. Pregled

Spring REST Docs generira dokumentaciju za RESTful usluge koja je istovremeno točna i čitljiva. Kombinira ručno napisanu dokumentaciju s automatski generiranim isječcima dokumenata izrađenim proljetnim testovima.

2. Prednosti

Jedna od glavnih filozofija projekta je korištenje testova za izradu dokumentacije. To osigurava da se uvijek generirana dokumentacija točno podudara sa stvarnim ponašanjem API-ja. Uz to, izlaz je spreman za obradu od strane Asciidoctor, izdavačkog lanca alata usredotočenog na sintaksu AsciiDoc. To je isti alat koji se koristi za generiranje dokumentacije Spring Framework-a.

Ovi pristupi smanjuju ograničenja koja nameću drugi okviri. Spring REST Docs proizvodi dokumentaciju koja je točna, sažeta i dobro strukturirana. Ova dokumentacija zatim omogućuje potrošačima web usluga da dobiju potrebne informacije s minimalnom mukom.

Alat ima još neke prednosti, kao što su:

• generiraju se isječci zahtjeva za curl i http
• jednostavno pakiranje dokumentacije u datoteku jar projekata
• lako dodati dodatne informacije u isječke
• podržava i JSON i XML

Testovi koji proizvode isječke mogu se napisati pomoću bilo koje podrške Spring MVC Test, Spring Webflux-a WebTestClient ili REST-Assured.

U našim ćemo primjerima koristiti Spring MVC testove, ali korištenje ostalih okvira vrlo je slično.

3. Ovisnosti

Idealan način za početak korištenja Spring REST dokumenata u projektu je korištenje sustava upravljanja ovisnostima. Ovdje koristimo Maven kao alat za izgradnju, tako da se donja ovisnost može kopirati i zalijepiti u vaš POM:

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

Ovdje također možete provjeriti novu verziju ovisnosti u Maven Central-u.

U našem primjeru trebamo proljeće-restdocs-mockmvc ovisnosti jer za izradu testova koristimo podršku za proljetni MVC test.

Ako želimo pisati testove pomoću WebTestClient ili REST Assured, trebat će nam ovisnosti spring-restdocs-webtestclient i spring-restdocs-restassured.

4. Konfiguracija

Kao što je spomenuto, koristit ćemo okvir Spring MVC Test za izradu zahtjeva za REST usluge koje treba dokumentirati. Pokretanje testa stvara isječke dokumentacije za zahtjev i rezultirajući odgovor.

Knjižnicu možemo koristiti i s testovima JUnit 4 i JUnit 5. Pogledajmo konfiguraciju potrebnu za svaku.

4.1. Konfiguracija JUnit 4

Prvi korak u generiranju isječaka dokumentacije za testove JUnit 4 je proglasiti javnošću JUnitRestDocumentation polje koje je označeno kao JUnit @Pravilo.

The JUnitRestDocumentation pravilo je konfigurirano s izlaznim direktorijumom u koji bi trebalo spremiti generirane isječke. Na primjer, ovaj direktorij može biti direktorij za izradu Mavena:

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

Dalje, postavili smo MockMvc kontekst tako da će biti konfiguriran za proizvodnju dokumentacije:

@Autowired privatni kontekst WebApplicationContext; privatni MockMvc mockMvc; @Before public void setUp () {this.mockMvc = MockMvcBuilders.webAppContextSetup (this.context) .apply (documentationConfiguration (this.restDocumentation)) .build (); }

The MockMvc objekt konfiguriran je pomoću MockMvcRestDocumentationConfigurer. Primjer ove klase može se dobiti iz statičkog documentationConfiguration () metoda na org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.

4.2. JUnit 5 Konfiguracija

Da bismo mogli raditi s testom JUnit 5, moramo ga proširiti s RestDocumentationExtention razred:

@ExtendWith ({RestDocumentationExtension.class, SpringExtension.class}) @SpringBootTest javna klasa ApiDocumentationJUnit5IntegrationTest {// ...}

Ova se klasa automatski konfigurira s / target / generated-snippets izlazni direktorij kada koristite Maven ili / build / generiraj-isječke za Gradle.

Dalje, moramo postaviti MockMvc primjer u @BeforeEach metoda:

@BeforeEach javna void setUp (WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {this.mockMvc = MockMvcBuilders.webAppContextSetup (webApplicationContext) .piguration (). }

Ako za testove ne koristimo JUnit, tada moramo koristiti ManualRestDocumentation razred.

5. ODMORNA usluga

Stvorimo CRUD RESTful uslugu koju možemo dokumentirati:

@RestController @RequestMapping ("/ crud") javna klasa CRUDController {@GetMapping javni popis čita (@RequestBody CrudInput crudInput) {Lista returnList = novi 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 ()); vratiti httpHeaders; } @DeleteMapping ("/ {id}") javno prazno brisanje (@PathVariable ("id") dugi id) {// delete}}

Zatim, dodajmo i IndexController koji vraća stranicu s vezom na CRUDController osnovna krajnja točka:

@RestController @RequestMapping ("/") javna klasa IndexController {statička klasa CustomRepresentationModel proširuje ReprezentacijaModel {javna CustomRepresentationModel (veza InitiLink) {super (InitialLink); }} @GetMapping javni CustomRepresentationModel indeks () {vratiti novi CustomRepresentationModel (linkTo (CRUDController.class) .withRel ("crud")); }}

6. JUNIT testovi

Natrag u testovima možemo koristiti MockMvc primjerice nazvati naše službe i dokumentirati zahtjev i odgovor.

Prvi, kako bi bili sigurni da svaki MockMvc poziv se automatski dokumentira bez daljnje konfiguracije koju možemo koristiti uvijekDa () metoda:

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

Ova postavka osigurava da svaki za svakoga MockMvc poziva, zadani isječci kreiraju se u mapi s nazivom metode ispitivanja. Također, primjenom prettyPrint () pretprocesor prikazuje isječke na lakši način čitljivosti.

Nastavimo s prilagođavanjem nekih naših poziva.

Da bismo dokumentirali našu indeksnu stranicu koja sadrži poveznicu, možemo se poslužiti statikom veze () metoda:

@Test public void indexExample () baca izuzetak {this.mockMvc.perform (get ("/")). AndExpect (status (). IsOk ()) .andDo (document ("index", links (linkWithRel ("crud") ) .description ("CRUD resurs")), responseFields (subsectionWithPath ("_ links") .description ("Links to other resources")) responseHeaders (headerWithName ("Content-Type") .description ("Content-Type of korisni teret ")))); }

Ovdje koristimo linkWithRel () metoda za dokumentiranje poveznice na / sirov.

Da biste dodali a Vrsta sadržaja zaglavlje odgovora koji ga dokumentiramo pomoću headerWithName () metodu i dodajući je u responseHeaders () metoda.

Također dokumentiramo korisni teret odgovora pomoću responseFields () metoda. To se može koristiti za dokumentiranje složenijeg pododsjeka odgovora ili pojedinačnog polja pomoću metoda subsectionWithPath () ili fieldWithPath ().

Slično korisnom opterećenju odgovora, također možemo dokumentirati korisni teret zahtjeva pomoću requestPayload ():

@Test public void crudCreateExample () baca iznimku {Map crud = new HashMap (); crud.put ("naslov", "Uzorak modela"); crud.put ("tijelo", "//www.baeldung.com/"); this.mockMvc.perform (post ("/ crud"). contentType (MediaTypes.HAL_JSON) .content (this.objectMapper.writeValueAsString (crud))) .andExpect (status (). isCreate ()) .andDo (document (" create-crud-example ", requestFields (fieldWithPath (" id "). description (" ID ulaza "), fieldWithPath (" title "). description (" Naslov unosa "), fieldWithPath (" body " ) .description ("Tijelo ulaza"),)))); }

U ovom smo primjeru dokumentirali naš POST zahtjev koji prima CrudInput model s poljima naslova i tijela i šalje STVORENI status. Svako se polje dokumentira pomoću fieldWithPath () metoda.

Da bismo dokumentirali zahtjev i parametar puta, možemo koristiti requestParameters () i pathParameters () metode. Obje metode koriste a parameterWithName () metoda za opisivanje svakog parametra:

@Test public void crudDeleteExample () baca iznimku {this.mockMvc.perform (delete ("/ crud / {id}", 10)). AndExpect (status (). IsOk ()) .andDo (document ("crud-delete -example ", pathParameters (parameterWithName (" id "). description (" ID ulaza za brisanje ")))); }

Ovdje smo dokumentirali našu krajnju točku za brisanje koja prima iskaznica parametar puta.

Projekt Spring REST Docs sadrži još snažnije funkcionalnosti dokumentacije, poput ograničenja polja i dijelova zahtjeva koji se mogu naći u dokumentaciji.

7. Izlaz

Nakon što se izrada uspješno izvodi, generirat će se isječci REST dokumenata dokumenata i spremiti u target / generirani isječci mapa:

Generirani izlaz sadržavat će informacije o usluzi, kako nazvati REST uslugu poput "curl" poziva, HTTP zahtjev i odgovor REST usluge te veze / krajnje točke na uslugu:

Naredba CURL

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

HTTP - OSTALI odgovor

[source, http, options = "nowrap"] ---- HTTP / 1.1 200 OK Content-type: application / hal + json; charset = UTF-8 Content-Length: 93 {"_links": {"crud": {"href": "// localhost: 8080 / crud"}}} ----

8. Korištenje isječaka za izradu dokumentacije

Da biste koristili isječke u većem dokumentu, možete ih uputiti pomoću Asciidoc uključuje. U našem smo slučaju stvorili dokument u src / dokumenti pozvao api-vodič.adoc:

U taj dokument, ako želimo uputiti isječak veza, možemo ga uključiti pomoću rezerviranog mjesta {snippets} koji će zamijeniti Maven kada obradi dokument:

==== Veze uključuju :: {snippets} /index-example/links.adoc []

9. Dodaci za Asciidocs Maven

Da bismo pretvorili API vodič iz Asciidoca u čitljiv format, možemo dodati Maven dodatak u životni ciklus izrade. Nekoliko je koraka kako biste to omogućili:

1. Primijenite dodatak Asciidoctor na pom.xml
2. Dodajte ovisnost o proljeće-restdocs-mockmvc u testSastaviti konfiguracija kako je spomenuto u odjeljku o ovisnostima
3. Konfigurirajte svojstvo za definiranje izlaznog mjesta za generirane isječke
4. Konfigurirajte test zadatak dodavanja direktorija isječaka kao izlaza
5. Konfigurirajte asciidoktor zadatak
6. Definirajte imenovani atribut isječci koji se može koristiti prilikom uključivanja generiranih isječaka u vašu dokumentaciju
7. Neka zadatak ovisi o test zadatak tako da se testovi pokrenu prije stvaranja dokumentacije
8. Konfigurirajte isječci direktorij kao ulaz. Svi generirani isječci bit će stvoreni u ovom direktoriju

Dodajte direktorij isječaka kao svojstvo u pom.xml pa dodatak Asciidoctor može koristiti ovu stazu za generiranje isječaka u ovoj mapi:

 $ {project.build.directory} / generirani isječci 

Konfiguracija dodatka Maven u pom.xml za generiranje Asciidoc isječaka iz gradnje je kao u nastavku:

 org.asciidoctor asciidoctor-maven-plugin 1.5.6 generiranje dokumenata paket-proces asciidoc html knjiga $ {snippetsDirectory} src / docs / asciidocs target / generated-docs 

10. Proces generiranja API dokumenata

Kada se Maven gradnja pokrene i testovi izvrše, svi isječci generirat će se u mapi isječaka pod konfiguriranim target / generirani-isječci imenik. Jednom kada se generiraju isječci, postupak izrade generira HTML izlaz.

Generirana HTML datoteka formatirana je i čitljiva, tako da je REST dokumentacija spremna za upotrebu. Svaki put kad se Maven izgrade, dokumenti se generiraju s najnovijim ažuriranjima.

11. Zaključak

Nemati dokumentaciju bolje je od pogrešne, ali proljetni REST dokumenti pomoći će u generiranju točne dokumentacije za RESTful usluge.

Kao službeni proljetni projekt, svoje ciljeve ostvaruje korištenjem tri testne knjižnice: Spring MVC Test, WebTestClient i OSTALO Osigurano. Ova metoda generiranja dokumentacije može pomoći u podršci testiranom pristupu razvoju i dokumentiranju RESTful API-ja.

Primjer projekta koji se temelji na kodu možete pronaći u ovom članku u povezanom spremištu GitHub.

Upravo sam najavio novo Uči proljeće tečaj, usredotočen na osnove Spring 5 i Spring Boot 2: