Documentando endpoints e modelos
Descreva operações com anotações.
Documentando endpoints e modelos é uma aula grátis de Spring Boot 4 Microservices & REST APIs no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Spring Boot 4 Microservices & REST APIs, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Spring Boot 4 Microservices & REST APIs inclui 4 aulas no total.
Partes desta aula ainda não foram traduzidas e aparecem em inglês.
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
Aprenda Java com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 24
- Aulas
- 93
Perguntas Frequentes
A aula “Documentando endpoints e modelos” é grátis?
Sim — o texto completo de “Documentando endpoints e modelos” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Spring Boot 4 Microservices & REST APIs, atualize para CoddyKit PRO. O curso de Spring Boot 4 Microservices & REST APIs inclui 4 aulas no total.
O que vou aprender em “Documentando endpoints e modelos”?
Descreva operações com anotações. Você pratica Spring Boot 4 Microservices & REST APIs com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Spring Boot 4 Microservices & REST APIs?
Nenhuma experiência prévia é necessária. Spring Boot 4 Microservices & REST APIs no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.
Quanto tempo leva a aula “Documentando endpoints e modelos”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Spring Boot 4 Microservices & REST APIs?
Sim. Cada aula de Spring Boot 4 Microservices & REST APIs inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Adicionando SpringDoc ao seu projeto
- Documentando endpoints e modelos
- Personalizando a especificação OpenAPI
- Swagger UI