Spring Boot 4 Microservices & REST APIs · Lekcja

Dokumentowanie endpointów i modeli

Opisuj operacje za pomocą adnotacji

Lekcja 2 z 413 kroki

Dokumentowanie endpointów i modeli to bezpłatna lekcja Spring Boot 4 Microservices & REST APIs na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Spring Boot 4 Microservices & REST APIs, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Spring Boot 4 Microservices & REST APIs zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

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.

Odpowiedz w interaktywnej lekcji

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

Bezpłatny start

Ucz się Java dzięki korepetycjom AI — za darmo

Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.

Kursy: 24
Lekcje: 93

Zacznij naukę bezpłatnie Wyświetl pełny kurs

Często zadawane pytania

Czy lekcja „Dokumentowanie endpointów i modeli” jest bezpłatna?

Tak — pełny tekst „Dokumentowanie endpointów i modeli” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Spring Boot 4 Microservices & REST APIs, przejdź na CoddyKit PRO. Kurs Spring Boot 4 Microservices & REST APIs zawiera 4 lekcji w sumie.

Co nauczysz się w „Dokumentowanie endpointów i modeli”?

Opisuj operacje za pomocą adnotacji Ćwiczysz Spring Boot 4 Microservices & REST APIs z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Spring Boot 4 Microservices & REST APIs?

Nie wymagamy żadnego doświadczenia. Spring Boot 4 Microservices & REST APIs w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Dokumentowanie endpointów i modeli”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Spring Boot 4 Microservices & REST APIs?

Tak. Każda lekcja Spring Boot 4 Microservices & REST APIs zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Spring Boot 4 Microservices & REST APIs