Swagger @ApiParam vs @ApiModelProperty
Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak:
>> ELLENŐRIZZE A FOLYAMATOT1. Áttekintés
Ebben az oktatóanyagban röviden áttekintjük a Swagger-t @ApiParam és @ApiModelProperty annotációk. Ezenkívül összehasonlítjuk ezeket a megjegyzéseket, és meghatározzuk az egyes alkalmazások helyes használatát.
2. Kulcskülönbség
Egyszerűen fogalmazva, @ApiParam és @ApiModelProperty a kommentárok különböző metaadatokat adnak a Swaggerhez. A @ApiParam az annotáció egy API erőforrás-kérelem paramétereire vonatkozik, míg @ApiModelProperty a modell tulajdonságaira vonatkozik.
3. @ApiParam
A @ApiParam az annotáció kizárólag a JAX-RS 1.x / 2.x paraméter annotációkhoz használható @PathParam, @QueryParam, @HeaderParam, @FormParam, és @BeanParam. Habár hullámzó alapértelmezés szerint beolvassa ezeket a kommentárokat, használhatjuk @ApiParam további részletek hozzáadásához a paraméterekhez vagy az értékek megváltoztatásához, ahogyan azokat a kódból olvassák.
A @ApiParam az annotáció segít megadni a paraméter nevét, típusát, leírását (értékét) és példapéldáját. Ezenkívül megadhatjuk, hogy a paraméter kötelező vagy opcionális.
Nézzük meg a használatát:
@RequestMapping (metódus = RequestMethod.POST, érték = "/ createUser", = = alkalmazás / json; charset = UTF-8 ") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiOperation (érték =" Felhasználó létrehozása ", megjegyzések = "Ez a módszer új felhasználót hoz létre") public Felhasználó createUser (@ApiParam (name = "keresztnév", type = "String", value = "A felhasználó keresztneve", example = "Vatsal", kötelező = true) @ RequestParam String firstName) {Felhasználó felhasználó = új Felhasználó (keresztnév); visszatérő felhasználó; }
Nézzük meg a Swagger felhasználói felület ábrázolását @ApiParam példa:
Most nézzük meg @ApiModelProperty.
4. @ApiModelProperty
A @ApiModelProperty annotáció lehetővé teszi számunkra a Swagger-specifikus definíciók, például a leírás (érték), a név, az adattípus, a példaértékek és a modell tulajdonságainak megengedett értékeinek vezérlését.
Ezenkívül további szűrési tulajdonságokat kínál arra az esetre, ha bizonyos esetekben el szeretnénk rejteni a tulajdonságot.
Adjunk hozzá néhány modelltulajdonságot a Felhasználókeresztnév terület:
@ApiModelProperty (érték = "a felhasználó keresztneve", név = "keresztnév", dataType = "karakterlánc", példa = "Vatsal") karakterlánc keresztnév;
Most vessünk egy pillantást a Felhasználó A modell specifikációi a Swagger felhasználói felületen:
5. Következtetés
Ebben a gyors cikkben két Swagger-kommentárt vizsgáltunk, amelyek segítségével metaadatokat adhatunk a paraméterekhez és a modell tulajdonságaihoz. Ezután megnéztünk néhány mintakódot az annotációk segítségével, és megláttuk azok ábrázolását a Swagger felhasználói felületen.
Mint mindig, ezek a kódminták elérhetők a GitHubon.
Java alsó