エンドポイントとモデルをドキュメント化する

Going beyond auto-detection

@Operation

@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

@GetMapping("/users")
public List<User> search(
    @Parameter(description = "Filter by city", example = "Berlin")
    @RequestParam(required = false) String city) {
    return service.search(city);
}

@ApiResponses

@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

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

@Schema(description = "Username",
        requiredMode = Schema.RequiredMode.REQUIRED,
        example = "neo")
private String username;

Documenting request bodies

@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

@Hidden
@GetMapping("/internal/metrics")
public Metrics internalOnly() { ... }

Grouping with @Tag

@Tag(name = "Users", description = "User management operations")
@RestController
@RequestMapping("/users")
public class UserController { ... }

Examples improve usability

Validation annotations show up too

Quick Check

Recap