Documenting Spring Boot REST APIs with OpenAPI and springdoc

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>3.2.0</version>
</dependency>

//DocumentedApiApp.java
package com.javabrahman.rest.openapi;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Positive;
import java.math.BigDecimal;
import java.util.List;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@Schema(description = "A book in the catalogue")
record Book(
    @Schema(description = "Catalogue id, assigned by the server", example = "1") long id,
    @Schema(description = "Title of the book", example = "Effective Java") String title,
    @Schema(description = "Price in US dollars", example = "45.99") BigDecimal price) {
}

@Schema(description = "The data needed to add a book")
record NewBook(
    @NotBlank @Schema(example = "Clean Code") String title,
    @Positive @Schema(example = "37.49") BigDecimal price) {
}

class BookNotFoundException extends RuntimeException {
  BookNotFoundException(long id) {
    super("No book with id " + id);
  }
}

@RestController
@RequestMapping("/api/books")
@Tag(name = "Books", description = "Browse and add books in the catalogue")
class BookController {

  @GetMapping
  @Operation(summary = "List all books")
  List<Book> all() {
    return List.of(new Book(1, "Effective Java", new BigDecimal("45.99")));
  }

  @GetMapping("/{id}")
  @Operation(summary = "Get one book")
  @ApiResponse(responseCode = "200", description = "The book")
  @ApiResponse(responseCode = "404", description = "No book with this id",
      content = @Content(mediaType = "application/problem+json", schema = @Schema(implementation = ProblemDetail.class)))
  Book one(@Parameter(description = "Catalogue id of the book", example = "1") @PathVariable long id) {
    if (id != 1) {
      throw new BookNotFoundException(id);
    }
    return all().getFirst();
  }

  @PostMapping
  @ResponseStatus(HttpStatus.CREATED)
  @Operation(summary = "Add a book", description = "Adds a book and returns it with its new id.")
  Book create(@Valid @RequestBody NewBook book) {
    return new Book(2, book.title(), book.price());
  }
}

@RestControllerAdvice
class ApiExceptionHandler {
  @ExceptionHandler(BookNotFoundException.class)
  ProblemDetail notFound(BookNotFoundException e) {
    return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, e.getMessage());
  }
}

@SpringBootApplication
public class DocumentedApiApp {

  @Bean
  OpenAPI apiInfo() {
    return new OpenAPI().info(new Info()
        .title("JavaBrahman Book Catalogue API")
        .version("1.0")
        .description("A small example API for the Spring REST tutorials.")
        .contact(new Contact().name("JavaBrahman").url("https://www.javabrahman.com")));
  }

  public static void main(String[] args) {
    SpringApplication.run(DocumentedApiApp.class, args);
  }
}