Perkhidmatan Mikro dan API REST Spring Boot 4 · Pelajaran

Mendokumentasikan Titik Akhir dan Model

Huraikan operasi menggunakan anotasi.

Pelajaran 2 daripada 413 langkah

Mendokumentasikan Titik Akhir dan Model ialah pelajaran Perkhidmatan Mikro dan API REST Spring Boot 4 percuma di CoddyKit. Ini ialah pelajaran 2 daripada 4. Anda boleh membaca keseluruhan pelajaran di bawah secara percuma — kemudian berlatih secara praktikal dalam pelayar menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Perkhidmatan Mikro dan API REST Spring Boot 4, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Perkhidmatan Mikro dan API REST Spring Boot 4 merangkumi sejumlah 4 pelajaran.

Melangkaui pengesanan automatik

Dokumentasi yang dijana secara automatik berfungsi tetapi ringkas. Anotasi daripada io.swagger.v3.oas.annotations membolehkan anda menambah penerangan mesra manusia, contoh dan butiran respons.

@Operation

@Operation mendokumenkan satu titik akhir: ringkasan pendek dan penerangan lebih panjang yang dipaparkan dalam UI.

@Operation(summary = "Get a user by id",
           description = "Returns a single user or 404 if not found")
@GetMapping("/users/{id}")
public User get(@PathVariable Long id) {
    return service.find(id);
}

@Parameter

@Parameter menerangkan parameter laluan, pertanyaan atau pengepala - maksudnya, sama ada diperlukan dan nilai contohnya.

@GetMapping("/users")
public List<User> search(
    @Parameter(description = "Filter by city", example = "Berlin")
    @RequestParam(required = false) String city) {
    return service.search(city);
}

@ApiResponses

Gunakan @ApiResponses untuk mendokumenkan setiap status HTTP yang mungkin dan maksudnya, termasuk kes ralat.

@ApiResponses({
  @ApiResponse(responseCode = "200", description = "User found"),
  @ApiResponse(responseCode = "404", description = "User not found")
})
@GetMapping("/users/{id}")
public User get(@PathVariable Long id) { ... }

@Schema pada model

@Schema mendokumenkan DTO dan medan-medannya - penerangan, contoh dan kekangan yang muncul dalam bahagian model UI.

public class User {
    @Schema(description = "Unique id", example = "42")
    private Long id;

    @Schema(description = "Email address", example = "a@b.com")
    private String email;
}

Menandakan medan yang diperlukan

Tetapkan requiredMode untuk menandakan medan sebagai wajib dalam skema, supaya pengguna tahu medan itu mesti hadir dalam permintaan.

@Schema(description = "Username",
        requiredMode = Schema.RequiredMode.REQUIRED,
        example = "neo")
private String username;

Mendokumenkan badan permintaan

@RequestBody (anotasi Swagger) menerangkan muatan. Selalunya anotasi @Schema DTO itu sendiri sudah mencukupi, tetapi anda juga boleh menambah penerangan dan contoh di sini.

@PostMapping("/users")
public User create(
    @io.swagger.v3.oas.annotations.parameters.RequestBody(
        description = "New user data", required = true)
    @org.springframework.web.bind.annotation.RequestBody User user) {
    return service.save(user);
}

Menyembunyikan perkara daripada dokumentasi

Gunakan @Hidden pada controller, kaedah atau medan untuk mengecualikannya daripada dokumentasi yang dijana - berguna untuk titik akhir dalaman.

@Hidden
@GetMapping("/internal/metrics")
public Metrics internalOnly() { ... }

Mengumpulkan dengan @Tag

@Tag mengumpulkan titik akhir berkaitan di bawah bahagian bernama dan diterangkan dalam UI - contohnya semua titik akhir pengguna di bawah "Pengguna".

@Tag(name = "Users", description = "User management operations")
@RestController
@RequestMapping("/users")
public class UserController { ... }

Contoh meningkatkan kebolehgunaan

Nilai example yang nyata pada parameter dan medan skema menjadikan dokumentasi jauh lebih berguna: pengguna boleh menyalin muatan yang realistik tanpa perlu meneka format.

Anotasi pengesahan turut dipaparkan

SpringDoc mencerminkan anotasi Pengesahan Bean Jakarta (@NotNull, @Size, @Min) ke dalam skema sebagai kekangan, supaya peraturan pengesahan anda menjadi sebahagian daripada kontrak yang didokumenkan.

Semakan ringkas

Semak pengetahuan anda tentang anotasi.

Jawab dalam pelajaran interaktif

Imbas kembali

Anda telah memperkayakan spesifikasi dengan anotasi:

@Operation + @ApiResponses menerangkan titik akhir dan status
@Parameter mendokumenkan input
@Schema mendokumenkan medan DTO dan kewajipannya
@Tag mengumpulkan, @Hidden mengecualikan

Percuma untuk bermula

Pelajari Java dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 24
Pelajaran: 93

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Mendokumentasikan Titik Akhir dan Model” percuma?

Ya — teks penuh “Mendokumentasikan Titik Akhir dan Model” boleh dibaca secara percuma di web ini. Untuk berlatih secara interaktif menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7, serta membuka kunci baki kursus Perkhidmatan Mikro dan API REST Spring Boot 4, tingkat taraf kepada CoddyKit PRO. Kursus Perkhidmatan Mikro dan API REST Spring Boot 4 merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Mendokumentasikan Titik Akhir dan Model”?

Huraikan operasi menggunakan anotasi. Anda berlatih Perkhidmatan Mikro dan API REST Spring Boot 4 menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan Perkhidmatan Mikro dan API REST Spring Boot 4?

Tiada pengalaman terdahulu diperlukan. Pembelajaran Perkhidmatan Mikro dan API REST Spring Boot 4 di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 2 daripada 4.

Berapa lamakah pelajaran “Mendokumentasikan Titik Akhir dan Model” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran Perkhidmatan Mikro dan API REST Spring Boot 4 ini?

Ya. Setiap pelajaran Perkhidmatan Mikro dan API REST Spring Boot 4 menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

← Kembali ke Perkhidmatan Mikro dan API REST Spring Boot 4