Dokumentera endpoints och modeller
Beskriv operationer med annoteringar.
Dokumentera endpoints och modeller är en gratis lektion i Spring Boot 4-mikrotjänster och REST API:er på CoddyKit. Detta är lektion 2 av 4. Ni kan läsa hela lektionen gratis nedan och sedan öva praktiskt i webbläsaren med en inbyggd kodredigerare och en AI-handledare som är tillgänglig dygnet runt. Den ingår i lärvägen för Spring Boot 4-mikrotjänster och REST API:er, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i Spring Boot 4-mikrotjänster och REST API:er innehåller totalt 4 lektioner.
Gå längre än automatisk upptäckt
Automatiskt genererad dokumentation fungerar, men är kortfattad. Annoteringar från io.swagger.v3.oas.annotations låter er lägga till användarvänliga beskrivningar, exempel och svarsdetaljer.
@Operation
@Operation dokumenterar en enskild endpoint: en kort sammanfattning och en längre beskrivning som visas i gränssnittet.
@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 beskriver en sökvägs-, query- eller headerparameter – dess innebörd, om den krävs och ett exempelvärde.
@GetMapping("/users")
public List<User> search(
@Parameter(description = "Filter by city", example = "Berlin")
@RequestParam(required = false) String city) {
return service.search(city);
}@ApiResponses
Använd @ApiResponses för att dokumentera varje möjlig HTTP-status och vad den betyder, inklusive felsituationer.
@ApiResponses({
@ApiResponse(responseCode = "200", description = "User found"),
@ApiResponse(responseCode = "404", description = "User not found")
})
@GetMapping("/users/{id}")
public User get(@PathVariable Long id) { ... }@Schema för modeller
@Schema dokumenterar en DTO och dess fält – beskrivningar, exempel och begränsningar som visas i gränssnittets modelldel.
public class User {
@Schema(description = "Unique id", example = "42")
private Long id;
@Schema(description = "Email address", example = "a@b.com")
private String email;
}Markera obligatoriska fält
Ange requiredMode för att markera ett fält som obligatoriskt i schemat, så att konsumenterna vet att det måste finnas med i anropen.
@Schema(description = "Username",
requiredMode = Schema.RequiredMode.REQUIRED,
example = "neo")
private String username;Dokumentera request-bodies
@RequestBody (Swagger-annoteringen) beskriver payloaden. Ofta räcker DTO:ns egna @Schema-annoteringar, men ni kan även lägga till en beskrivning och ett exempel här.
@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);
}Dölj sådant från dokumentationen
Använd @Hidden på en controller, metod eller ett fält för att utesluta det från den genererade dokumentationen – praktiskt för interna endpoints.
@Hidden
@GetMapping("/internal/metrics")
public Metrics internalOnly() { ... }Gruppera med @Tag
@Tag grupperar relaterade endpoints under en namngiven sektion med beskrivning i gränssnittet – till exempel alla användar-endpoints under "Users".
@Tag(name = "Users", description = "User management operations")
@RestController
@RequestMapping("/users")
public class UserController { ... }Exempel förbättrar användbarheten
Konkreta example-värden för parametrar och schemafält gör dokumentationen mycket mer användbar: konsumenterna kan kopiera realistiska payloads i stället för att gissa format.
Valideringsannoteringar visas också
SpringDoc återspeglar Jakarta Bean Validation-annoteringar (@NotNull, @Size, @Min) i schemat som begränsningar, så att era valideringsregler blir en del av det dokumenterade kontraktet.
Snabbkontroll
Kontrollera era kunskaper om annoteringar.
Sammanfattning
Ni har berikat specifikationen med annoteringar:
@Operation+@ApiResponsesbeskriver endpoints och statuskoder@Parameterdokumenterar indata@Schemadokumenterar DTO-fält och obligatoriska fält@Taggrupperar och@Hiddenutesluter
Lär dig Java med en AI-lärare – gratis
Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.
- Kurser
- 24
- Lektioner
- 93
Vanliga frågor
Är lektionen ”Dokumentera endpoints och modeller” gratis?
Ja – hela texten till ”Dokumentera endpoints och modeller” kan läsas gratis här på webben. Om Ni vill öva interaktivt med en inbyggd kodredigerare och en AI-handledare som är tillgänglig dygnet runt och låsa upp resten av kursen i Spring Boot 4-mikrotjänster och REST API:er, kan Ni uppgradera till CoddyKit PRO. Kursen i Spring Boot 4-mikrotjänster och REST API:er innehåller totalt 4 lektioner.
Vad lär jag mig i ”Dokumentera endpoints och modeller”?
Beskriv operationer med annoteringar. Ni övar på Spring Boot 4-mikrotjänster och REST API:er med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.
Behöver jag någon erfarenhet för att börja lära mig Spring Boot 4-mikrotjänster och REST API:er?
Du behöver inga förkunskaper. Utbildningen i Spring Boot 4-mikrotjänster och REST API:er på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 2 av 4.
Hur lång tid tar lektionen ”Dokumentera endpoints och modeller”?
De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.
Kan jag skriva och köra kod i den här Spring Boot 4-mikrotjänster och REST API:er-lektionen?
Ja. Varje Spring Boot 4-mikrotjänster och REST API:er-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.
Alla lektioner i den här kursen
- Lägga till SpringDoc i projektet
- Dokumentera endpoints och modeller
- Anpassa OpenAPI-specifikationen
- Swagger UI