记录端点和模型
使用注解描述操作
记录端点和模型 是 CoddyKit 上的免费 Spring Boot 4 Microservices & REST APIs 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Spring Boot 4 Microservices & REST APIs 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Spring Boot 4 Microservices & REST APIs 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
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
常见问题解答
「记录端点和模型」课时是免费的吗？
是的 — 「记录端点和模型」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Spring Boot 4 Microservices & REST APIs 课程的其余内容，请升级到 CoddyKit PRO。 Spring Boot 4 Microservices & REST APIs 课程共包含 4 节课。
「记录端点和模型」这节课中我会学到什么？
使用注解描述操作 你通过在浏览器中直接运行的动手代码来练习 Spring Boot 4 Microservices & REST APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Spring Boot 4 Microservices & REST APIs 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Spring Boot 4 Microservices & REST APIs 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。
「记录端点和模型」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Spring Boot 4 Microservices & REST APIs 课中编写并运行代码吗？
能。每节 Spring Boot 4 Microservices & REST APIs 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。