Spring Boot 4 Microservices & REST APIs · Lesson

Documenting Endpoints and Models

Describe operations with annotations.

Documenting Endpoints and Models is a free Spring Boot 4 Microservices & REST APIs lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Microservices & REST APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

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 + @ApiResponses describe endpoints and statuses
@Parameter documents inputs
@Schema documents DTO fields and required-ness
@Tag groups, @Hidden excludes

Frequently asked questions

Is the “Documenting Endpoints and Models” lesson free?

Yes — the full text of “Documenting Endpoints and Models” is free to read here on the web, and the Spring Boot 4 Microservices & REST APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Microservices & REST APIs course, upgrade to CoddyKit PRO.

What will I learn in “Documenting Endpoints and Models”?

Describe operations with annotations. You practise Spring Boot 4 Microservices & REST APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Microservices & REST APIs?

No prior experience is required. Spring Boot 4 Microservices & REST APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Documenting Endpoints and Models” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Microservices & REST APIs lesson?

Yes. Every Spring Boot 4 Microservices & REST APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Spring Boot 4 Microservices & REST APIs