Documenter les points de terminaison et les modèles
Décrivez les opérations avec des annotations.
Documenter les points de terminaison et les modèles est une leçon Spring Boot 4 Microservices & REST APIs gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Spring Boot 4 Microservices & REST APIs, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Spring Boot 4 Microservices & REST APIs comprend 4 leçons au total.
Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.
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
Questions Fréquemment Posées
La leçon « Documenter les points de terminaison et les modèles » est-elle gratuite ?
Oui — le texte complet de « Documenter les points de terminaison et les modèles » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Spring Boot 4 Microservices & REST APIs, passe à CoddyKit PRO. Le cours Spring Boot 4 Microservices & REST APIs comprend 4 leçons au total.
Qu'est-ce que j'apprendrai dans « Documenter les points de terminaison et les modèles » ?
Décrivez les opérations avec des annotations. Tu pratiques Spring Boot 4 Microservices & REST APIs avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.
Dois-je avoir de l'expérience pour commencer Spring Boot 4 Microservices & REST APIs ?
Aucune expérience préalable n'est requise. Spring Boot 4 Microservices & REST APIs sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.
Combien de temps prend la leçon « Documenter les points de terminaison et les modèles » ?
La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.
Peux-tu écrire et exécuter du code dans cette leçon Spring Boot 4 Microservices & REST APIs ?
Oui. Chaque leçon Spring Boot 4 Microservices & REST APIs inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.
Toutes les leçons de ce cours
- Ajouter SpringDoc à votre projet
- Documenter les points de terminaison et les modèles
- Personnaliser la spécification OpenAPI
- Swagger UI