streamalism.org

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

1. Pregled

U ovom uputstvu kratko ćemo se osvrnuti na Swaggerovo @ApiParam i @ApiModelProperty bilješke. Nadalje, usporedit ćemo ove bilješke i utvrditi ispravnu upotrebu za svaku.

2. Ključna razlika

Jednostavno rečeno, @ApiParam i @ApiModelProperty bilješke dodaju različite metapodatke Swaggeru. The @ApiParam napomena je za parametre zahtjeva za resursom API-ja, dok @ApiModelProperty je za svojstva modela.

3. @ApiParam

The @ApiParam napomena je namijenjena samo za bilješke parametara JAX-RS 1.x / 2.x poput @PathParam, @QueryParam, @HeaderParam, @FormParam, i @BeanParam. Iako razmetljiva jezgra skeniramo ove bilješke prema zadanim postavkama, možemo ih koristiti @ApiParam da biste dodali više detalja o parametrima ili promijenili vrijednosti dok se čitaju iz koda.

The @ApiParam napomena pomaže odrediti naziv, vrstu, opis (vrijednost) i primjer vrijednosti parametra. Štoviše, možemo odrediti je li parametar potreban ili nije.

Pogledajmo njegovu upotrebu:

@RequestMapping (method = RequestMethod.POST, value = "/ createUser", produce = "application / json; charset = UTF-8") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiOperation (value = "Create user", notes) = "Ova metoda stvara novog korisnika") javni korisnik createUser (@ApiParam (name = "firstName", type = "String", value = "First Name of the user", example = "Vatsal", required = true) @ RequestParam String firstName) {User user = novi korisnik (firstName); povratni korisnik; }

Pogledajmo prikaz Swagger UI za naš @ApiParam primjer:

Pogledajmo sada @ApiModelProperty.

4. @ApiModelProperty

The @ApiModelProperty bilješka omogućuje nam kontrolu nad Swaggerovim definicijama poput opisa (vrijednosti), imena, tipa podataka, primjera vrijednosti i dopuštenih vrijednosti za svojstva modela.

Također, nudi dodatna svojstva filtriranja u slučaju da želimo sakriti svojstvo u određenim scenarijima.

Dodajmo nekoliko svojstava modela u Korisnikovime polje:

@ApiModelProperty (value = "ime korisnika", name = "firstName", dataType = "String", example = "Vatsal") String firstName;

Sada, pogledajmo Korisnik Specifikacije modela u korisničkom sučelju Swagger:

5. Zaključak

U ovom smo kratkom članku pogledali dvije Swaggerove bilješke pomoću kojih možemo dodati metapodatke za parametre i svojstva modela. Zatim smo pogledali neki uzorak koda koristeći te napomene i vidjeli njihove prikaze u korisničkom sučelju Swagger.

Kao i uvijek, svi su ovi uzorci koda dostupni na GitHub-u.

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