Introduktion til Spring REST Docs

REST Top

Jeg har lige annonceret det nye Lær foråret kursus med fokus på det grundlæggende i Spring 5 og Spring Boot 2:

>> KONTROLLER KURSEN

1. Oversigt

Spring REST Docs genererer dokumentation til RESTful-tjenester, der er både nøjagtige og læsbare. Den kombinerer håndskrevet dokumentation med automatisk genererede dokumentuddrag produceret med Spring-tests.

2. Fordele

En vigtig filosofi bag projektet er brugen af ​​test til at producere dokumentationen. Dette sikrer, at dokumentationen, der altid genereres nøjagtigt, matcher den faktiske adfærd for API'en. Derudover er output klar til at blive behandlet af Asciidoctor, en udgivelsesværktøjskæde centreret omkring AsciiDoc-syntaksen. Dette er det samme værktøj, der bruges til at generere Spring Framework's dokumentation.

Disse tilgange reducerer begrænsningerne i andre rammer. Spring REST Docs producerer dokumentation, der er nøjagtig, kortfattet og velstruktureret. Denne dokumentation giver derefter webserviceforbrugerne mulighed for at få de oplysninger, de har brug for med et minimum af besvær.

Værktøjet har nogle andre fordele, såsom:

  • curl- og http-anmodningsuddrag genereres
  • nem at pakke dokumentation i projekter jar fil
  • let at tilføje ekstra information til uddragene
  • understøtter både JSON og XML

Testene, der producerer uddragene, kan skrives ved hjælp af enten Spring MVC Test support, Spring Webflux WebTestClient eller REST-forsikret.

I vores eksempler skal vi bruge Spring MVC-test, men det er meget ens at bruge de andre rammer.

3. Afhængigheder

Den ideelle måde at komme i gang med Spring REST Docs i et projekt er ved hjælp af et afhængighedsstyringssystem. Her bruger vi Maven som byggeværktøj, så afhængigheden nedenfor kan kopieres og indsættes i din POM:

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

Du kan også tjekke Maven Central for en ny version af afhængigheden her.

I vores eksempel har vi brug for spring-restdocs-mockmvc afhængighed, da vi bruger Spring MVC test support til at oprette vores tests.

Hvis vi ønsker at skrive tests ved hjælp af WebTestClient eller REST Assured, har vi brug for afhængighed af spring-restdocs-webtestclient og spring-restdocs-restassured.

4. Konfiguration

Som nævnt bruger vi Spring MVC Test framework til at stille anmodninger til REST-tjenesterne, der skal dokumenteres. At køre testen producerer dokumentationsuddrag til anmodningen og det resulterende svar.

Vi kan bruge biblioteket med både JUnit 4 og JUnit 5 test. Lad os se den nødvendige konfiguration for hver.

4.1. JUnit 4-konfiguration

Det allerførste trin i generering af dokumentationsuddrag til JUnit 4-test er at erklære en offentlighed JUnitRestDocumentation felt, der er kommenteret som en JUnit @Herske.

Det JUnitRestDocumentation regel er konfigureret med det outputmappe, hvor de genererede uddrag skal gemmes. For eksempel kan denne mappe være den udbyggede mappe for Maven:

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

Derefter opretter vi MockMvc kontekst, så den konfigureres til at producere dokumentation:

@Autowired privat WebApplicationContext-kontekst; private MockMvc mockMvc; @Før offentlig ugyldig setUp () {this.mockMvc = MockMvcBuilders.webAppContextSetup (this.context) .apply (documentationConfiguration (this.restDocumentation)) .build (); }

Det MockMvc objekt er konfigureret ved hjælp af en MockMvcRestDocumentationConfigurer. En forekomst af denne klasse kan fås fra det statiske dokumentationKonfiguration () metode til org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.

4.2. JUnit 5-konfiguration

For at arbejde med en JUnit 5-test skal vi udvide testen med RestDocumentationExtension klasse:

@ExtendWith ({RestDocumentationExtension.class, SpringExtension.class}) @SpringBootTest offentlig klasse ApiDocumentationJUnit5IntegrationTest {// ...}

Denne klasse konfigureres automatisk med en / mål / genereret-uddrag outputkatalog, når du bruger Maven eller / build / generere-uddrag til Gradle.

Derefter skal vi oprette MockMvc eksempel i en @BeforeEach metode:

@BeforeEach public void setUp (WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {this.mockMvc = MockMvcBuilders.webAppContextSetup (webApplicationContext) .apply (documentationConfiguration (restDocumentation)). }

Hvis vi ikke bruger JUnit til testene, skal vi bruge ManualRestDocumentation klasse.

5. RESTful service

Lad os oprette en CRUD RESTful service, som vi kan dokumentere:

@RestController @RequestMapping ("/ crud") public class CRUDController {@GetMapping public List read (@RequestBody CrudInput crudInput) {List returnList = new ArrayList (); returnList.add (crudInput); returner returnList; } @ResponseStatus (HttpStatus.CREATED) @PostMapping public HttpHeaders save (@RequestBody CrudInput crudInput) {HttpHeaders httpHeaders = new HttpHeaders (); httpHeaders.setLocation (linkTo (CRUDController.class) .slash (crudInput.getTitle ()). toUri ()); returner httpHeaders; } @DeleteMapping ("/ {id}") offentlig ugyldig sletning (@PathVariable ("id") lang id) {// slet}}

Lad os derefter tilføje en IndexController der returnerer en side med et link til CRUDController base slutpunkt:

@RestController @RequestMapping ("/") offentlig klasse IndexController {statisk klasse CustomRepresentationModel udvider RepresentationModel {public CustomRepresentationModel (Link initialLink) {super (initialLink); }} @GetMapping offentligt CustomRepresentationModel indeks () {returner nyt CustomRepresentationModel (linkTo (CRUDController.class) .withRel ("crud")); }}

6. JUnit-tests

Tilbage i testene kan vi bruge MockMvc eksempel for at ringe til vores tjenester og dokumentere anmodningen og svaret.

Først, for at sikre hver MockMvc opkald dokumenteres automatisk uden yderligere konfiguration, vi kan bruge altid gør () metode:

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

Denne opsætning sikrer, at hver for enhver MockMvc opkald, oprettes standarduddragene i en mappe med testmetodens navn. Også anvendelse af prettyPrint () pre-processor viser uddragene på en lettere læsbar måde.

Lad os fortsætte med at tilpasse nogle af vores opkald.

For at dokumentere vores indeksside, der indeholder et link, kan vi bruge det statiske links () metode:

@Test offentligt ugyldigt indexExample () kaster undtagelse {this.mockMvc.perform (get ("/")). Og Expect (status (). IsOk ()). Og gør (dokument ("index", links (linkWithRel ("crud") ) .description ("CRUD-ressourcen")), responseFields (subsectionWithPath ("_ links") .description ("Links til andre ressourcer")) responseHeaders (headerWithName ("Content-Type") .description ("Content-Type of nyttelasten ")))); }

Her bruger vi linkWithRel () metode til at dokumentere et link til / crud.

For at tilføje en Indholdstype header til svaret, vi dokumenterer det ved hjælp af headerWithName () metode og tilføje den til responseHeaders () metode.

Vi dokumenterer også svarets nyttelast ved hjælp af responsFields () metode. Dette kan bruges til at dokumentere et mere komplekst underafsnit af svaret eller et enkelt felt ved hjælp af metoderne subsectionWithPath () eller fieldWithPath ().

Svarende til svarets nyttelast, vi kan også dokumentere anmodningen nyttelast ved hjælp af requestPayload ():

@Test offentlig ugyldig crudCreateExample () kaster undtagelse {Map crud = ny HashMap (); crud.put ("title", "Sample Model"); crud.put ("body", "//www.baeldung.com/"); this.mockMvc.perform (post ("/ crud"). contentType (MediaTypes.HAL_JSON) .content (this.objectMapper.writeValueAsString (crud))). og Expect (status (). isCreated ()). andDo (document (" create-crud-example ", requestFields (fieldWithPath (" id "). beskrivelse (" ID'et for input "), fieldWithPath (" title "). beskrivelse (" Titlen på input "), fieldWithPath (" body " ) .description ("The input of the input"),)))); }

I dette eksempel har vi dokumenteret vores POST-anmodning, der modtager en CrudInput model med titel- og kropsfelter og sender en OPRETTET status. Hvert felt dokumenteres ved hjælp af fieldWithPath () metode.

For at dokumentere anmodning og sti-parameter kan vi bruge requestParameters () og pathParameters () metoder. Begge metoder bruger en parameterWithName () metode til at beskrive hver parameter:

@Test offentlig ugyldig crudDeleteExample () kaster undtagelse {this.mockMvc.perform (delete ("/ crud / {id}", 10)). Og Expect (status (). IsOk ()). Og Do (dokument ("crud-delete) -eksempel ", pathParameters (parameterWithName (" id "). beskrivelse (" Id for input, der skal slettes "))); }

Her har vi dokumenteret vores sletteendepunkt, der modtager et id sti-parameter.

Spring REST Docs-projektet indeholder endnu mere kraftfulde dokumentationsfunktioner, såsom feltbegrænsninger og anmodningsdele, der kan findes i dokumentationen.

7. Output

Når build'en kører med succes, genereres output fra REST docs-uddrag og gemmes i mål / genereret-uddrag folder:

Det genererede output vil have information om tjenesten, hvordan man ringer til REST-tjenesten som 'krølle' -opkald, HTTP-anmodning og svar fra REST-tjenesten og links / slutpunkter til tjenesten:

CURL-kommando

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

HTTP - REST-svar

[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. Brug af uddrag til at oprette dokumentation

For at bruge uddragene i et større dokument kan du henvise til dem ved hjælp af Asciidoc inkluderer. I vores tilfælde har vi oprettet et dokument i src / docs hedder api-guide.adoc:

I dette dokument, hvis vi ønsker at henvise til linkuddraget, kan vi inkludere det ved hjælp af en pladsholder {uddrag} der erstattes af Maven, når det behandler dokumentet:

==== Links inkluderer :: {snippets} /index-eksempel/links.adoc []

9. Asciidocs Maven-plugins

For at konvertere API-guiden fra Asciidoc til et læsbart format kan vi tilføje et Maven-plugin til byggets livscyklus. Der er flere trin for at aktivere dette:

  1. Anvend Asciidoctor-pluginet til pom.xml
  2. Tilføj en afhængighed af spring-restdocs-mockmvc i testKompilér konfiguration som nævnt i afsnittet om afhængigheder
  3. Konfigurer en egenskab til at definere outputplaceringen for genererede uddrag
  4. Konfigurer prøve opgave at tilføje uddragskataloget som output
  5. Konfigurer asciidoctor opgave
  6. Definer en attribut med navnet uddrag der kan bruges, når de genererede uddrag inkluderes i din dokumentation
  7. Gør opgaven afhængig af prøve opgave, så testene køres, før dokumentationen oprettes
  8. Konfigurer uddrag bibliotek som input. Alle de genererede uddrag oprettes under denne mappe

Tilføj kodestykket som en egenskab i pom.xml så Asciidoctor-pluginet kan bruge denne sti til at generere uddrag under denne mappe:

 $ {project.build.directory} / genereret-uddrag 

Maven-plugin-konfigurationen i pom.xml at generere Asciidoc-uddrag fra build er som nedenfor:

 org.asciidoctor asciidoctor-maven-plugin 1.5.6 generer-docs pakke proces-asciidoc html bog $ {snippetsDirectory} src / docs / asciidocs target / generated-docs 

10. API Doc-genereringsproces

Når Maven-build'en kører, og testene udføres, genereres alle uddrag i mappen uddrag under den konfigurerede mål / genereret-uddrag vejviser. Når uddragene er genereret, genererer byggeprocessen HTML-output.

Den genererede HTML-fil er formateret og læsbar, så REST-dokumentationen er klar til brug. Hver gang Maven build kører, genereres dokumenterne også med de nyeste opdateringer.

11. Konklusion

At have ingen dokumentation er bedre end forkert dokumentation, men Spring REST-dokumenter hjælper med at generere nøjagtig dokumentation til RESTful-tjenester.

Som et officielt forårsprojekt opnår det sine mål ved hjælp af tre testbiblioteker: Spring MVC Test, WebTestClient og REST forsikret. Denne metode til generering af dokumentation kan hjælpe med at støtte en testdrevet tilgang til udvikling og dokumentation af RESTful API'er.

Du kan finde et eksempel på et projekt baseret på koden i denne artikel i det linkede GitHub-lager.

REST bunden

Jeg har lige annonceret det nye Lær foråret kursus med fokus på det grundlæggende i Spring 5 og Spring Boot 2:

>> KONTROLLER KURSEN

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