Swagger @ApiParam vs @ApiModelProperty

Java Teratas

Saya baru sahaja mengumumkan kursus Learn Spring yang baru , yang berfokus pada asas-asas Spring 5 dan Spring Boot 2:

>> SEMAK KURSUS

1. Gambaran keseluruhan

Dalam tutorial ini, kita akan melihat secara ringkas anotasi Swagger's @ApiParam dan @ApiModelProperty . Selanjutnya, kami akan membandingkan anotasi ini dan mengenal pasti penggunaan yang betul untuk masing-masing.

2. Perbezaan Utama

Ringkasnya , anotasi @ApiParam dan @ApiModelProperty menambah metadata yang berbeza untuk Swagger. The @ApiParam anotasi adalah untuk parameter permintaan sumber API, manakala @ApiModelProperty adalah untuk hartanah model.

3. @ApiParam

The @ApiParam anotasi adalah untuk kegunaan semata-mata dengan JAX-RS 1.x / 2.x parameter penjelasan seperti @PathParam , @QueryParam , @HeaderParam , @FormParam dan @BeanParam . Walaupun inti swagger mengimbas anotasi ini secara lalai, kami dapat menggunakan @ApiParam untuk menambahkan lebih banyak perincian mengenai parameter atau mengubah nilai ketika dibaca dari kod.

The @ApiParam anotasi membantu untuk menentukan nama, jenis, penerangan (nilai), dan contoh nilai parameter. Selain itu, kita dapat menentukan sama ada parameter tersebut diperlukan atau pilihan.

Mari lihat penggunaannya:

@RequestMapping( method = RequestMethod.POST, value = "/createUser", produces = "application/json; charset=UTF-8") @ResponseStatus(HttpStatus.CREATED) @ResponseBody @ApiOperation(value = "Create user", notes = "This method creates a new user") public User createUser( @ApiParam( name = "firstName", type = "String", value = "First Name of the user", example = "Vatsal", required = true) @RequestParam String firstName) { User user = new User(firstName); return user; }

Mari lihat perwakilan Swagger UI untuk contoh @ApiParam kami :

Sekarang, mari lihat @ApiModelProperty .

4. @ApiModelProperty

The @ApiModelProperty anotasi membolehkan kita untuk mengawal definisi Swagger khusus seperti keterangan (nilai), nama, jenis data, nilai-nilai sebagai contoh, dan nilai yang dibenarkan bagi hartanah model.

Ia juga menawarkan sifat penapisan tambahan sekiranya kami ingin menyembunyikan harta tanah dalam senario tertentu.

Mari tambahkan beberapa sifat model ke medan FirstName Pengguna :

@ApiModelProperty( value = "first name of the user", name = "firstName", dataType = "String", example = "Vatsal") String firstName;

Sekarang, mari kita lihat spesifikasi Model Pengguna di Swagger UI:

5. Kesimpulan

Dalam artikel ringkas ini, kami melihat dua anotasi Swagger yang dapat kami gunakan untuk menambahkan metadata untuk parameter dan sifat model. Kemudian, kami melihat beberapa contoh kod menggunakan anotasi tersebut dan melihat perwakilannya di Swagger UI.

Seperti biasa, semua contoh kod ini terdapat di GitHub.

Bahagian bawah Java

Saya baru sahaja mengumumkan kursus Learn Spring yang baru , yang berfokus pada asas-asas Spring 5 dan Spring Boot 2:

>> SEMAK KURSUS