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 és az OpenAPI 3.0 az API dokumentáció létrehozásának két módja egy REST API-hoz.

Ebben az oktatóanyagban megvizsgáljuk azok relatív előnyeit és hátrányait.

2. A származás rövid összefoglalása

A Spring REST Docs egy keretrendszer, amelyet a Spring közösség fejlesztett ki a RESTful API-k pontos dokumentációjának elkészítése érdekében. Tesztvezérelt megközelítést igényel, ahol a dokumentációt vagy Spring MVC tesztként, Spring Webflux-ként írják WebTestClient, vagy REST-biztosított.

A tesztek futtatásának kimenete AsciiDoc fájlokként jön létre, amelyeket az Asciidoctor segítségével össze lehet állítani egy HTML oldal létrehozására, amely leírja az API-kat. Mivel a TDD módszert követi, a Spring REST Docs automatikusan hozza minden előnyét mint például kevesebb hibára hajlamos kód, kevesebb átdolgozás és gyorsabb visszacsatolási ciklus, hogy csak néhányat említsünk.

Az OpenAPI viszont a Swagger 2.0-ból született specifikáció. Ennek legújabb verziója a 3.0-ás, és számos ismert megvalósítással rendelkezik.

Mint bármely más specifikáció, az OpenAPI meghatároz bizonyos alapszabályokat a megvalósítások követésére. Egyszerűen fogalmazva, minden Az OpenAPI implementációknak állítólag JSON objektumként kell elkészíteniük a dokumentációt JSON vagy YAML formátumban.

Sok olyan eszköz is létezik, amely beveszi ezt a JSON / YAML-t és kiköp egy felhasználói felületet az API megjelenítéséhez és navigálásához. Ez jól jön például az elfogadási teszt során. Az itt található kódmintáinkban ezt fogjuk használni springdoc - könyvtár az OpenAPI 3 programhoz Spring Boot alkalmazással.

Mielőtt részletesen áttekintenénk a kettőt, állítsunk be gyorsan egy dokumentálandó API-t.

3. A REST API

Állítsunk össze egy alap CRUD API-t a Spring Boot segítségével.

3.1. A tárház

Itt a tárház, amelyet használni fogunk, csupasz csont PagingAndSortingRepository interfész, a modellel Foo:

@Repository nyilvános felület A FooRepository kiterjeszti a PagingAndSortingRepository {} @Entity Foo {@Id @GeneratedValue (strategy = GenerationType.IDENTITY) privát hosszú azonosítót; @Column (nullable = false) privát karakterlánc címe; @Column () private String body; // kivitelező, mérőeszközök és beállítók}

A tárolót az a használatával is betöltjük schema.sql és a adatok.sql.

3.2. A Vezérlő

Ezután nézzük meg a vezérlőt, és rövidítsük át a megvalósítás részleteit:

@RestController @RequestMapping ("/ foo") nyilvános osztályú FooController {@Autowired FooRepository adattár; @GetMapping public ResponseEntity getAllFoos () {// implementáció} @GetMapping (value = "{id}") nyilvános ResponseEntity getFooById (@PathVariable ("id") hosszú id) {// implementáció} @PostMapping public ResponseEntity addFoo (@RequestBody @Valid Foo foo ) {// implementáció} @DeleteMapping ("/ {id}") nyilvános ResponseEntity deleteFoo (@PathVariable ("id") hosszú id) {// implementáció} @PutMapping ("/ {id}") nyilvános ResponseEntity updateFoo (@ PathVariable ("id") hosszú azonosító, @RequestBody Foo foo) {// implementáció}}

3.3. Az alkalmazás

És végül a Boot App:

@SpringBootApplication () public class Application {public static void main (String [] args) {SpringApplication.run (Application.class, args); }}

4. OpenAPI / Springdoc

Most nézzük meg, hogyan springdoc dokumentációt adhat hozzá Foo REST API.

Emlékezz erre az objektum alapján létrehoz egy JSON-objektumot és az API felhasználói felületét.

4.1. Alap felhasználói felület

Először csak hozzáadunk néhány Maven-függőséget - springdoc-openapi-data-rest a JSON előállításához, és springdoc-openapi-ui a felhasználói felület megjelenítéséért.

Az eszköz megvizsgálja az API kódját, és elolvassa a vezérlő metódusainak kommentárjait. Ezen az alapon létrehozza az API JSON-t, amely élni fog // localhost: 8080 / api-docs /. Ez egy alap felhasználói felületet is szolgál majd //localhost:8080/swagger-ui-custom.html:

Mint láthatjuk, egyáltalán semmilyen kód hozzáadása nélkül, egy gyönyörű látványt kaptunk az API-ról, egészen a Foo séma. Használni a Próbáld ki gombra, akár végrehajthatjuk a műveleteket és megtekinthetjük az eredményeket.

Most, mi lenne, ha valódi dokumentációt szeretnénk hozzáadni az API-hoz? Ami az API lényege, mit jelent az összes művelete, mit kell bevinni és milyen válaszokra kell számítani?

Ezt a következő szakaszban vizsgáljuk meg.

4.2. Részletes felhasználói felület

Először nézzük meg, hogyan lehet általános leírást hozzáadni az API-hoz.

Ehhez hozzáadunk egy OpenAPI bab a Boot alkalmazásunkhoz:

@Bean public OpenAPI customOpenAPI (@Value ("$ {springdoc.version}") String appVersion) {visszatér az új OpenAPI (). Info (új Info () .title ("Foobar API") .version (appVersion) .description ( "Ez egy minta Foobar szerver, amelyet a springdocs -" + "könyvtár segítségével hoztak létre az OpenAPI 3 számára tavaszi indítással.") .TermsOfService ("// swagger.io/terms/") .license (új licenc (). Név (" Apache 2.0 ") .url (" // springdoc.org "))); } 

Ezután néhány információt hozzáadva az API műveleteihez, néhány OpenAPI-specifikus kommentárral díszítjük a leképezéseket.

Lássuk, hogyan tudjuk leírni getFooById. Ezt egy másik vezérlőn belül fogjuk megtenni, FooBarController, ami hasonló a miénkhez FooController:

@RestController @RequestMapping ("/ foobar") @Tag (name = "foobar", description = "a foobar API dokumentációs megjegyzésekkel") public class FooBarController {@Autowired FooRepository repository; @Operation (összefoglaló = "Get foo foo id alapján") @ApiResponses (value = {@ApiResponse (responseCode = "200", description = "megtalálta a foo-t", content = {@Content (mediaType = "application / json") , schema = @Schema (implementáció = Foo.class))}), @ApiResponse (responseCode = "400", description = "Érvénytelen azonosító van megadva, content = @Content), @ApiResponse (responseCode =" 404 ", description = "Foo not found", content = @Content)}) @GetMapping (value = "{id}") public ResponseEntity getFooById (@Parameter (description = "keresendő foo azonosítója") @PathVariable ("id") karakterlánc id) {// a rövidítés miatt kihagyott megvalósítás} // egyéb hozzárendelések, hasonlóan a @Operation és @ApiResponses jelölésekkel} 

Most nézzük meg a felhasználói felületre gyakorolt ​​hatást:

Tehát ezekkel a minimális konfigurációkkal az API-nk felhasználói láthatják, miről van szó, hogyan kell használni, és milyen eredményekre számíthatunk. Csak annyit kellett tennünk, hogy lefordítottuk a kódot és futtattuk a Boot alkalmazást.

5. Tavaszi REST Docs

A REST docs teljesen másfajta elfogadás az API dokumentációban. Amint azt korábban leírtuk, a folyamat tesztvezérelt, és a kimenet statikus HTML oldal formájában van.

Az itt látható példánkban a tavaszi MVC teszteket fogjuk használni dokumentációs részletek létrehozásához.

Először hozzá kell adnunk a tavasz-restdocs-mockmvc függőség és a asciidoc Maven plugin a mi oldalunkra pom.

5.1. A JUnit5 teszt

Most nézzük meg a JUnit5 tesztet, amely tartalmazza a dokumentációnkat:

@ExtendWith ({RestDocumentationExtension.class, SpringExtension.class}) @SpringBootTest (class = Application.class) nyilvános osztály SpringRestDocsIntegrationTest {private MockMvc mockMvc; @Autowired private ObjectMapper objectMapper; @BeforeEach public void setup (WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {this.mockMvc = MockMvcBuilders.webAppContextSetup (webApplicationContext) .apply (dokumentációConfiguration) (restDocument). } @Test public void, amikor aGetFooById_thenSuccessful () kiveti a {Kivétel {ConstraintDescriptions desc = új ConstraintDescriptions (Foo.class) kivételt; this.mockMvc.perform (get ("/ foo / {id}", 1)) .andExpect (status (). isOk ()) .andDo (dokumentum ("getAFoo", preprocessRequest (prettyPrint ()), preprocessResponse (prettyPrint ()), pathParameters (paraméterWithName ("id"). description ("keresendő foo azonosítója")), responseFields (fieldWithPath ("id") .description ("A foo azonosítója" + collectionToDelimitedString (desc.descriptionsForProperty ("id"), ".")), fieldWithPath ("title"). leírás ("the foo címe"), fieldWithPath ("body"). leírás ("the foo törzse")))) ; } // további vizsgálati módszerek más leképezések lefedésére

}

A teszt futtatása után több fájlt kapunk célok / generált kivonatok könyvtár az adott API műveletről. Különösen, whenGetFooById_thenSuccessful nyolcat ad nekünk adocs a getAFoo mappát a könyvtárban.

Itt egy minta http-response.adoctermészetesen a válasz testet tartalmazza:

[forrás, http, options = "nowrap"] ---- HTTP / 1.1 200 OK Tartalom-típus: alkalmazás / json Tartalom-hossz: 60 {"id": 1, "title": "Foo 1", "body ":" Foo body 1 "} ----

5.2. fooapi.adoc

Most szükségünk van egy mester fájlra, amely ezeket a részleteket összeszőve egy jól strukturált HTML-t alkot.

Nevezzük fooapi.adoc és meglátja annak egy kis részét:

=== Hozzáférés a foo-hoz GET A `GET` kérést használjuk a foo olvasásához. ==== A kérelem struktúrája :: :: {kivonatok} /getAFoo/http-request.adoc [] ==== Az elérési út paraméterei tartalmazzák a következőt: {{kivonatok} /getAFoo/path-parameters.adoc [] ==== Példa válaszra include :: {snippets} /getAFoo/http-response.adoc [] ==== CURL kérelem tartalmazza :: {snippets} /getAFoo/curl-request.adoc []

A. Végrehajtása után asciidoctor-maven-plugin, megkapjuk a végleges HTML fájlt fooapi.html ban,-ben target / generated-docs mappába.

És ez így fog kinézni, amikor egy böngészőben megnyitja:

6. Key Takeaways

Most, hogy megvizsgáltuk a megvalósításokat, foglaljuk össze az előnyöket és hátrányokat.

Val vel springdoc, az általunk használt kommentárok összezavarták a többi vezérlő kódunkat és csökkentették annak olvashatóságát. Ezenkívül a dokumentáció szorosan összekapcsolódott a kóddal, és utat enged a gyártásnak.

Mondanom sem kell, hogy a dokumentáció karbantartása újabb kihívást jelent itt - ha valami megváltozik az API-ban, a programozó mindig emlékezne a megfelelő OpenAPI kommentár frissítésére?

Másrészről, A REST Docs nem tűnik annyira fülbemászónak, mint a másik kezelőfelület, és nem is használható elfogadási tesztelésre. De megvannak a maga előnyei.

Különösen a a tavaszi MVC teszt nemcsak a részleteket adja meg nekünk, hanem az API-t is ellenőrzi, mint bármely más egység teszt. Ez arra kényszerít minket, hogy az API módosításainak megfelelő dokumentációs változtatásokat hajtsunk végre, ha vannak ilyenek. Ezenkívül a dokumentációs kód teljesen elkülönül a megvalósítástól.

De megint a másik oldalon, több kódot kellett írnunk a dokumentáció előállításához. Először maga a teszt, amely vitathatatlanul olyan bőbeszédű, mint az OpenAPI kommentárok, másodszor pedig a master adoc.

További lépésekre van szüksége a végső HTML előállításához - először futtassa a tesztet, majd a plugint. Springdoc csak a Boot App futtatására volt szükség.

7. Következtetés

Ebben az oktatóanyagban megvizsgáltuk az OpenAPI alapú különbségeket springdoc és tavaszi REST Docs. Azt is láttuk, hogy miként lehet megvalósítani a kettőt egy dokumentáció létrehozásához egy alap CRUD API-hoz.

Összefoglalva, mindkettőnek megvannak az előnyei és hátrányai, és az egyik használatának eldöntése egyedi követelményeink függvénye.

Mint mindig, a forráskód is elérhető a GitHubon.

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