Spring Boot 4 Microservices & REST APIs · Lektion

Endpunkte und Modelle dokumentieren

Beschreiben Sie Operationen mit Annotationen.

Endpunkte und Modelle dokumentieren ist eine kostenlose Spring Boot 4 Microservices & REST APIs-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Spring Boot 4 Microservices & REST APIs-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Spring Boot 4 Microservices & REST APIs-Kurs umfasst insgesamt 4 Lektionen.

Teile dieser Lektion wurden noch nicht übersetzt und werden auf Englisch angezeigt.

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

Häufig gestellte Fragen

Ist die Lektion „Endpunkte und Modelle dokumentieren“ kostenlos?

Ja — der vollständige Text von „Endpunkte und Modelle dokumentieren“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Spring Boot 4 Microservices & REST APIs-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Spring Boot 4 Microservices & REST APIs-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Endpunkte und Modelle dokumentieren“?

Beschreiben Sie Operationen mit Annotationen. Du übst Spring Boot 4 Microservices & REST APIs mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um Spring Boot 4 Microservices & REST APIs zu starten?

Keine Vorkenntnisse erforderlich. Spring Boot 4 Microservices & REST APIs auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.

Wie lange dauert die Lektion „Endpunkte und Modelle dokumentieren“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser Spring Boot 4 Microservices & REST APIs-Lektion Code schreiben und ausführen?

Ja. Jede Spring Boot 4 Microservices & REST APIs-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu Spring Boot 4 Microservices & REST APIs