Sombong @ApiParam vs @ApiParam

Java Top

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

>> LIHAT KURSUSnya

1. Ikhtisar

Dalam tutorial ini, kita akan secara singkat melihat menyombongkan @ApiParam dan @ApiModelProperty penjelasan. Selanjutnya, kami akan membandingkan anotasi ini dan mengidentifikasi penggunaan yang benar untuk masing-masing.

2. Perbedaan Kunci

Sederhananya , anotasi @ApiParam dan @ApiModelProperty menambahkan metadata yang berbeda ke Swagger. The @ApiParam penjelasan adalah untuk parameter permintaan sumber daya API, sedangkan @ApiModelProperty adalah untuk properti dari model.

3. @ApiParam

The @ApiParam penjelasan untuk digunakan semata-mata dengan JAX-RS 1.x / 2.x parameter penjelasan seperti @PathParam , @QueryParam , @HeaderParam , @FormParam , dan @BeanParam . Meskipun swagger-core memindai anotasi ini secara default, kita dapat menggunakan @ApiParam untuk menambahkan lebih banyak detail tentang parameter atau mengubah nilai saat dibaca dari kode.

The @ApiParam penjelasan membantu untuk menentukan nama, jenis, deskripsi (value), dan nilai contoh parameter. Selain itu, kami dapat menentukan apakah parameter tersebut diperlukan atau opsional.

Mari kita 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 kita lihat representasi UI Swagger untuk contoh @ApiParam kami :

Sekarang, mari kita lihat @ApiModelProperty .

4. @ApiModelProty

The @ApiModelProperty penjelasan memungkinkan kita untuk mengontrol definisi Swagger-spesifik seperti deskripsi (value), nama, tipe data, misalnya nilai-nilai, dan nilai-nilai diperbolehkan untuk sifat model.

Selain itu, ia menawarkan properti pemfilteran tambahan jika kita ingin menyembunyikan properti dalam skenario tertentu.

Mari tambahkan beberapa properti model ke bidang NamaDepan 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 singkat ini, kita melihat dua anotasi Swagger yang dapat kita gunakan untuk menambahkan metadata untuk parameter dan properti model. Kemudian, kami melihat beberapa kode contoh menggunakan anotasi tersebut dan melihat representasi mereka di UI Swagger.

Seperti biasa, semua contoh kode ini tersedia di GitHub.

Jawa bawah

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

>> LIHAT KURSUSnya