Documentare endpoint e modelli
Descriva le operazioni con le annotazioni.
Documentare endpoint e modelli è una lezione Spring Boot 4 Microservices & REST APIs gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Spring Boot 4 Microservices & REST APIs, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Spring Boot 4 Microservices & REST APIs include 4 lezioni in totale.
Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.
Going beyond auto-detection
Auto-generated docs are functional but terse. Annotations from io.swagger.v3.oas.annotations let you add human-friendly descriptions, examples and response details.
@Operation
@Operation documents a single endpoint: a short summary and a longer description shown in the 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 describes a path, query or header parameter - its meaning, whether it is required, and an example value.
@GetMapping("/users")
public List<User> search(
@Parameter(description = "Filter by city", example = "Berlin")
@RequestParam(required = false) String city) {
return service.search(city);
}@ApiResponses
Use @ApiResponses to document each possible HTTP status and what it means, including error cases.
@ApiResponses({
@ApiResponse(responseCode = "200", description = "User found"),
@ApiResponse(responseCode = "404", description = "User not found")
})
@GetMapping("/users/{id}")
public User get(@PathVariable Long id) { ... }@Schema on models
@Schema documents a DTO and its fields - descriptions, examples, and constraints that appear in the model section of the UI.
public class User {
@Schema(description = "Unique id", example = "42")
private Long id;
@Schema(description = "Email address", example = "a@b.com")
private String email;
}Marking required fields
Set requiredMode to mark a field as mandatory in the schema, so consumers know it must be present in requests.
@Schema(description = "Username",
requiredMode = Schema.RequiredMode.REQUIRED,
example = "neo")
private String username;Documenting request bodies
@RequestBody (the Swagger one) describes the payload. Often the DTO's own @Schema annotations are enough, but you can add a description and example here too.
@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);
}Hiding things from docs
Use @Hidden on a controller, method, or field to exclude it from the generated documentation - handy for internal endpoints.
@Hidden
@GetMapping("/internal/metrics")
public Metrics internalOnly() { ... }Grouping with @Tag
@Tag groups related endpoints under a named, described section in the UI - e.g. all user endpoints under "Users".
@Tag(name = "Users", description = "User management operations")
@RestController
@RequestMapping("/users")
public class UserController { ... }Examples improve usability
Concrete example values on parameters and schema fields make the docs far more useful: consumers can copy realistic payloads instead of guessing formats.
Validation annotations show up too
SpringDoc reflects Jakarta Bean Validation annotations (@NotNull, @Size, @Min) into the schema as constraints, so your validation rules become part of the documented contract.
Quick Check
Check your annotation knowledge.
Recap
You enriched the spec with annotations:
@Operation+@ApiResponsesdescribe endpoints and statuses@Parameterdocuments inputs@Schemadocuments DTO fields and required-ness@Taggroups,@Hiddenexcludes
Impara Java con un tutor IA — gratis
Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.
- Corsi
- 24
- Lezioni
- 93
Domande Frequenti
La lezione «Documentare endpoint e modelli» è gratuita?
Sì — il testo completo di «Documentare endpoint e modelli» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Spring Boot 4 Microservices & REST APIs, passa a CoddyKit PRO. Il corso Spring Boot 4 Microservices & REST APIs include 4 lezioni in totale.
Cosa imparerò in «Documentare endpoint e modelli»?
Descriva le operazioni con le annotazioni. Eserciti Spring Boot 4 Microservices & REST APIs con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare Spring Boot 4 Microservices & REST APIs?
Non è richiesta alcuna esperienza precedente. Spring Boot 4 Microservices & REST APIs su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.
Quanto tempo richiede la lezione «Documentare endpoint e modelli»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione Spring Boot 4 Microservices & REST APIs?
Sì. Ogni lezione Spring Boot 4 Microservices & REST APIs include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Aggiungere SpringDoc al progetto
- Documentare endpoint e modelli
- Personalizzare la specifica OpenAPI
- Swagger UI