Spring Boot Course · Lesson 14

Documenting the API with OpenAPI

The Library API has ten endpoints, and the only way to learn them is to read the controllers or the lessons. A client developer has neither. This lesson gives the API a description that machines and people can both read — an OpenAPI spec, generated from the code by springdoc-openapi — and a page, Scalar, where anyone can browse the endpoints, copy a ready-made request and send it from the browser. Then it fixes what the generator gets wrong, and adds the descriptions only a person can write, without burying the controllers under them.

The win

/v3/api-docs serves an OpenAPI spec of the Library API, and /docs shows it as a reference you can try every endpoint from: the right status codes, page/size/sort as real parameters, the problem responses each operation can return, and a summary, description and example for every operation and field. The documentation lives in BookApi and AuthorApi interfaces, so the controllers stay as short as they were, and the page loads nothing from outside the app — no AI chat, its fonts served by the app itself. A test checks the spec is served and still says what the annotations put there.

A description of the API, generated from the code

OpenAPI is the standard way to describe an HTTP API: one JSON or YAML document listing every path and operation, its parameters, its request and response bodies, and the schema of each body ^[spec]. Tools read it: documentation pages render it, code generators build clients from it, API gateways and contract tests check requests against it.

You could write that document by hand, and then keep it in step with the code by hand, forever. Instead, the course generates the spec from the running application with springdoc-openapi: it reads the application's Spring MVC mappings — paths, HTTP methods, @PathVariables, @RequestBody records, return types, even the Bean Validation constraints — and serves the result ^[docs]. A new endpoint appears in the docs the moment it exists, and a renamed field is renamed in the docs too.

Step 1 — Add springdoc and look at what it generates

springdoc-openapi is not part of Spring Boot, so its version isn't managed by the parent: you name it. Version 3.x is the line for Spring Boot 4 ^[docs]; this lesson uses 3.1.1, the current release. Add it below uuid-creator:


83 collapsed lines
1
<?xml version="1.0" encoding="UTF-8"?>
2
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4
    <modelVersion>4.0.0</modelVersion>
5
    <parent>
6
        <groupId>org.springframework.boot</groupId>
7
        <artifactId>spring-boot-starter-parent</artifactId>
8
        <version>4.1.1</version>
9
        <relativePath/> <!-- lookup parent from repository -->
10
    </parent>
11
    <groupId>com.example</groupId>
12
    <artifactId>library</artifactId>
13
    <version>0.0.1-SNAPSHOT</version>
14
    <name>library</name>
15
    <description/>
16
    <url/>
17
    <licenses>
18
        <license/>
19
    </licenses>
20
    <developers>
21
        <developer/>
22
    </developers>
23
    <scm>
24
        <connection/>
25
        <developerConnection/>
26
        <tag/>
27
        <url/>
28
    </scm>
29
    <properties>
30
        <java.version>21</java.version>
31
    </properties>
32
    <dependencies>
33
        <dependency>
34
            <groupId>org.springframework.boot</groupId>
35
            <artifactId>spring-boot-starter-webmvc</artifactId>
36
        </dependency>
37

38
        <!-- Bean Validation (@Valid + constraints); brings Hibernate Validator -->
39
        <dependency>
40
            <groupId>org.springframework.boot</groupId>
41
            <artifactId>spring-boot-starter-validation</artifactId>
42
        </dependency>
43

44
        <!-- Spring Data JPA + Hibernate -->
45
        <dependency>
46
            <groupId>org.springframework.boot</groupId>
47
            <artifactId>spring-boot-starter-data-jpa</artifactId>
48
        </dependency>
49

50
        <!-- PostgreSQL JDBC driver (used at runtime to talk to the database) -->
51
        <dependency>
52
            <groupId>org.postgresql</groupId>
53
            <artifactId>postgresql</artifactId>
54
            <scope>runtime</scope>
55
        </dependency>
56

57
        <!-- Liquibase migrations. The autoconfiguration lives in this module (it brings
58
             liquibase-core transitively); the bare org.liquibase:liquibase-core won't activate it. -->
59
        <dependency>
60
            <groupId>org.springframework.boot</groupId>
61
            <artifactId>spring-boot-liquibase</artifactId>
62
        </dependency>
63

64
        <!-- Starts/stops the Postgres container from compose.yaml when the app runs -->
65
        <dependency>
66
            <groupId>org.springframework.boot</groupId>
67
            <artifactId>spring-boot-docker-compose</artifactId>
68
            <optional>true</optional>
69
        </dependency>
70

71
        <!-- Lombok: generates getters/constructors/equals at compile time -->
72
        <dependency>
73
            <groupId>org.projectlombok</groupId>
74
            <artifactId>lombok</artifactId>
75
            <optional>true</optional>
76
        </dependency>
77

78
        <!-- uuid-creator: time-ordered UUIDv7 generation -->
79
        <dependency>
80
            <groupId>com.github.f4b6a3</groupId>
81
            <artifactId>uuid-creator</artifactId>
82
            <version>6.0.0</version>  <!-- or the latest on Maven Central -->
83
        </dependency>
84

85
        <!-- springdoc-openapi: generates the OpenAPI spec from the controllers, serves it with Scalar -->
86
        <dependency>
87
            <groupId>org.springdoc</groupId>
88
            <artifactId>springdoc-openapi-starter-webmvc-scalar</artifactId>
89
            <version>3.1.1</version>
90
        </dependency>
91

37 collapsed lines
92
        <dependency>
93
            <groupId>org.springframework.boot</groupId>
94
            <artifactId>spring-boot-starter-webmvc-test</artifactId>
95
            <scope>test</scope>
96
        </dependency>
97

98
        <!-- @DataJpaTest and TestEntityManager: the persistence-layer test slice -->
99
        <dependency>
100
            <groupId>org.springframework.boot</groupId>
101
            <artifactId>spring-boot-starter-data-jpa-test</artifactId>
102
            <scope>test</scope>
103
        </dependency>
104

105
        <!-- @ServiceConnection: points Spring Boot at a database Testcontainers started -->
106
        <dependency>
107
            <groupId>org.springframework.boot</groupId>
108
            <artifactId>spring-boot-testcontainers</artifactId>
109
            <scope>test</scope>
110
        </dependency>
111

112
        <!-- Testcontainers' PostgreSQL module: runs postgres in Docker for the tests -->
113
        <dependency>
114
            <groupId>org.testcontainers</groupId>
115
            <artifactId>testcontainers-postgresql</artifactId>
116
            <scope>test</scope>
117
        </dependency>
118
    </dependencies>
119

120
    <build>
121
        <plugins>
122
            <plugin>
123
                <groupId>org.springframework.boot</groupId>
124
                <artifactId>spring-boot-maven-plugin</artifactId>
125
            </plugin>
126
        </plugins>
127
    </build>
128

129
</project>

The webmvc-scalar starter brings both halves: the spec generator for Spring MVC, and Scalar, the page that renders the spec ^[docs]. Nothing else to configure. Start the app:

./mvnw spring-boot:run

Open http://localhost:8080/scalar in your browser. The sidebar lists the endpoints, grouped by controller; pick one to see its parameters, request body and responses, with a curl command for it on the right and a "Test Request" button that sends it from the page.

The course serves the docs with Scalar, through springdoc's own Scalar module: it reads as a reference, and every operation comes with a request you can copy into a terminal. The page you'll meet most often in Spring projects is Swagger UI, which renders the same spec as a list of expandable operations with a "Try it out" button. It is the same choice of one dependency — springdoc-openapi-starter-webmvc-ui instead, served at /swagger-ui.html ^[docs] — and nothing else in this lesson changes, because both pages render the spec springdoc generates.

The spec behind the page is at http://localhost:8080/v3/api-docs. It is one long line; most browsers offer to pretty-print it. Three parts of it — the API's info, the /api/books path with its two operations, and the CreateBookRequest schema:

"info": {
  "title": "OpenAPI definition",
  "version": "v0"
},
…
"/api/books": {
  "get": {
    "tags": [
      "book-controller"
    ],
    "operationId": "all",
    "parameters": [
      {
        "name": "authorId",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      {
        "name": "pageable",
        "in": "query",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Pageable"
        }
      }
    ],
    "responses": {
      "200": { … }
    }
  },
  "post": {
    "tags": [
      "book-controller"
    ],
    "operationId": "create",
    "requestBody": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateBookRequest"
          }
        }
      },
      "required": true
    },
    "responses": {
      "200": {
        "description": "OK",
        "content": {
          "*/*": {
            "schema": {
              "$ref": "#/components/schemas/BookResponse"
            }
          }
        }
      }
    }
  }
},
…
"CreateBookRequest": {
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1
    },
    "year": {
      "type": "integer",
      "format": "int32",
      "exclusiveMinimum": 0
    },
    "authorIds": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "minItems": 1,
      "uniqueItems": true
    }
  },
  "required": [
    "authorIds",
    "title"
  ]
}

A lot is right, with no annotation at all:

Every path and method is there, with authorId as an optional query parameter of type string, format uuid — from @RequestParam(required = false) UUID.
The request body is CreateBookRequest, and its schema carries Lesson 7's constraints: @NotBlank became minLength: 1, @Positive became exclusiveMinimum: 0, @NotEmpty became minItems: 1, and the two non-null fields are required. A Set is an array with uniqueItems.
The response body is BookResponse, and the list's is PagedModelBookResponse — Lesson 8's stable { content, page } shape, the one the API really sends.

Lesson 1's /hello endpoint is in the list too, under hello-controller.

It got four things wrong, though, and a client trusting the docs would be misled by each:

POST answers 201, not 200. The controller returns a ResponseEntity, and the status in it is decided at runtime by ResponseEntity.created(...). springdoc can only see the type, so it assumes the default.
There is no parameter called pageable. Lesson 8's Pageable is filled from three query parameters, page, size and sort; springdoc sees one method parameter of type Pageable and documents it as one required object.
No operation can fail, according to the spec: no 404, no 400, no 409. springdoc does read @ExceptionHandler methods, but only learns their status from @ResponseStatus ^[docs]; Lesson 7's handlers return a ProblemDetail that carries its status inside. And even with @ResponseStatus, springdoc would add every handler's status to every operation — a 409 on GET /api/books too, which can't happen.
The names are placeholders. The API is called "OpenAPI definition", version v0, and the endpoints are grouped under book-controller and author-controller, the class names.

Stop the app with Ctrl+C. The next steps fix all four, and add what no generator can know: what each operation is for and what each field means.

Every operation gets a summary and its full list of responses, error responses included, and every parameter and every request and response field a description and an example. The docs are the API's front page — for a client developer, and for anyone looking at the project — and the code can only supply its shape, never its meaning.

Step 2 — Name the API

The title, version and description at the top of the spec come from an OpenAPI bean, if the application declares one ^[docs]. Give it a small configuration class of its own, in a new config package:

1
package com.example.library.config;
2

3
import io.swagger.v3.oas.models.OpenAPI;
4
import io.swagger.v3.oas.models.info.Info;
5
import org.springframework.context.annotation.Bean;
6
import org.springframework.context.annotation.Configuration;
7

8
@Configuration(proxyBeanMethods = false)
9
public class OpenApiConfig {
10

11
    @Bean
12
    OpenAPI libraryOpenApi() {
13
        return new OpenAPI().info(new Info()
14
            .title("Library API")
15
            .version("v1")
16
            .description("Books and their authors. Errors are RFC 9457 problem details (application/problem+json)."));
17
    }
18
}

OpenAPI, Info are the Swagger library's Java model of an OpenAPI document (io.swagger.v3.oas.models), which springdoc uses underneath. springdoc starts from this bean and adds the paths and schemas it generates.
The description says what every error looks like, once for the whole API: Lesson 7's RFC 9457 problem details.
@Configuration(proxyBeanMethods = false), as on Lesson 12's TestcontainersConfiguration, lets Spring use the class exactly as written. The callout below explains what it switches off.

What proxyBeanMethods = false switches off

By default, Spring doesn't use a @Configuration class as you wrote it: at startup it generates a subclass of it, a proxy, and uses that instead ^[docs]. The proxy is there for configurations whose @Bean methods call each other, as in this made-up one:

1
@Configuration
2
public class ImportConfig {
3

4
    @Bean
5
    IdGenerator idGenerator() {
6
        return new IdGenerator();
7
    }
8

9
    @Bean
10
    BookImporter bookImporter() {
11
        return new BookImporter(idGenerator());   // calls the other @Bean method
12
    }
13
}

In plain Java, every call to idGenerator() runs the method again and returns a new IdGenerator, so BookImporter would get a different one from the bean Spring registered. The proxy overrides idGenerator(): the call returns the bean the container already holds, so the bean stays one object however often the method is called.

proxyBeanMethods = false asks for no proxy. Spring uses the class as written, and each @Bean method is an ordinary factory method that Spring calls once. That is safe whenever no @Bean method calls another — OpenApiConfig and TestcontainersConfiguration each have a single one — and it saves generating the subclass at startup. Spring Boot's own auto-configuration classes are written this way, and Spring Initializr generates TestcontainersConfiguration with it. A configuration without the proxy can still wire one bean into another: it takes the bean as a parameter, BookImporter bookImporter(IdGenerator idGenerator), and Spring passes in the one it holds.

Step 3 — Describe the errors once

Every error the API sends comes from Lesson 7's ApiExceptionHandler, as a problem body like this one — GET /api/books/{id} for a book that doesn't exist:

{"detail":"No book with id 01a125d2-f80e-7ba4-aa2d-d296d723ecb7","instance":"/api/books/01a125d2-f80e-7ba4-aa2d-d296d723ecb7","status":404,"title":"Resource not found"}

The usual way to document such a body is to point at Spring's ProblemDetail class, @Schema(implementation = ProblemDetail.class), and let springdoc describe it. That describes the Java class, not the JSON: it lists a type the API leaves out, and a properties object that never appears — Spring writes those extra properties, such as validation's errors, at the top level — and the docs page fills the example with placeholders, "title": "string", "status": 1. A client reading it learns nothing about this API's errors.

So each error response is described once, in ProblemResponses, with a schema of the fields the API really sends and an example copied from a real response, and the operations refer to it by name. The errors are shared — the same "no book with this id" comes from GET, PUT and DELETE — so describing them in one place also keeps them consistent. The class sits next to OpenApiConfig:

1
package com.example.library.config;
2

3
import java.util.LinkedHashMap;
4
import java.util.Map;
5
import io.swagger.v3.oas.models.Components;
6
import io.swagger.v3.oas.models.examples.Example;
7
import io.swagger.v3.oas.models.media.Content;
8
import io.swagger.v3.oas.models.media.IntegerSchema;
9
import io.swagger.v3.oas.models.media.MediaType;
10
import io.swagger.v3.oas.models.media.ObjectSchema;
11
import io.swagger.v3.oas.models.media.Schema;
12
import io.swagger.v3.oas.models.media.StringSchema;
13
import io.swagger.v3.oas.models.responses.ApiResponse;
14

15
// The API's error responses, each described once, with the body ApiExceptionHandler really sends.
16
public final class ProblemResponses {
17

18
    // The names BookApi and AuthorApi refer to: @ApiResponse(responseCode = "404", ref = BOOK_NOT_FOUND)
19
    public static final String MALFORMED_BOOK_ID = "MalformedBookId";
20
    public static final String INVALID_BOOK = "InvalidBook";
21
    public static final String INVALID_BOOK_OR_ID = "InvalidBookOrId";
22
    public static final String BOOK_NOT_FOUND = "BookNotFound";
23
    public static final String UNKNOWN_AUTHOR_ID = "UnknownAuthorId";
24
    public static final String BOOK_OR_AUTHOR_NOT_FOUND = "BookOrAuthorNotFound";
25
    public static final String MALFORMED_AUTHOR_ID = "MalformedAuthorId";
26
    public static final String INVALID_AUTHOR = "InvalidAuthor";
27
    public static final String INVALID_AUTHOR_OR_ID = "InvalidAuthorOrId";
28
    public static final String AUTHOR_NOT_FOUND = "AuthorNotFound";
29
    public static final String AUTHOR_HAS_BOOKS = "AuthorHasBooks";
30

31
    // The same ids as the parameter and record examples
32
    private static final String BOOK_ID = "01a125d2-f80e-7ba4-aa2d-d296d723ecb7";
33
    private static final String AUTHOR_ID = "01a125d2-f7d2-77d5-a5a7-945523ee5cc1";
34

35
    private ProblemResponses() {}
36

37
    static Components components() {
38
        Map<String, String> bookErrors = new LinkedHashMap<>();
39
        bookErrors.put("year", "must be greater than 0");
40
        bookErrors.put("title", "must not be blank");
41
        bookErrors.put("authorIds", "must not be empty");
42
        Map<String, String> authorErrors = new LinkedHashMap<>();
43
        authorErrors.put("name", "must not be blank");
44

45
        Example malformedBookId = problem("The id is not a UUID",
46
            "Failed to convert 'id' with value: 'not-a-uuid'", "/api/books/not-a-uuid", 400, "Bad Request");
47
        Example invalidNewBook = invalid("/api/books", bookErrors);
48
        Example invalidBook = invalid("/api/books/" + BOOK_ID, bookErrors);
49
        Example bookNotFound = problem("No book with this id",
50
            "No book with id " + BOOK_ID, "/api/books/" + BOOK_ID, 404, "Resource not found");
51
        Example unknownAuthorOfNewBook = problem("An author id doesn't exist",
52
            "No author with id [" + AUTHOR_ID + "]", "/api/books", 404, "Resource not found");
53
        Example unknownAuthorOfBook = problem("An author id doesn't exist",
54
            "No author with id [" + AUTHOR_ID + "]", "/api/books/" + BOOK_ID, 404, "Resource not found");
55
        Example malformedAuthorId = problem("The id is not a UUID",
56
            "Failed to convert 'id' with value: 'not-a-uuid'", "/api/authors/not-a-uuid", 400, "Bad Request");
57
        Example invalidNewAuthor = invalid("/api/authors", authorErrors);
58
        Example invalidAuthor = invalid("/api/authors/" + AUTHOR_ID, authorErrors);
59
        Example authorNotFound = problem("No author with this id",
60
            "No author with id " + AUTHOR_ID, "/api/authors/" + AUTHOR_ID, 404, "Resource not found");
61
        Example authorHasBooks = problem("The author still has books",
62
            "Author " + AUTHOR_ID + " still has books; delete or re-author them first", "/api/authors/" + AUTHOR_ID,
63
            409, "Conflict");
64

65
        return new Components()
66
            .addSchemas("Problem", problemSchema())
67
            .addResponses(MALFORMED_BOOK_ID, response("The id is not a UUID", malformedBookId))
68
            .addResponses(INVALID_BOOK, response("The request body is invalid", invalidNewBook))
69
            .addResponses(INVALID_BOOK_OR_ID, response("The request body is invalid, or the id is not a UUID",
70
                invalidBook, malformedBookId))
71
            .addResponses(BOOK_NOT_FOUND, response("No book with this id", bookNotFound))
72
            .addResponses(UNKNOWN_AUTHOR_ID, response("An author id doesn't exist", unknownAuthorOfNewBook))
73
            .addResponses(BOOK_OR_AUTHOR_NOT_FOUND, response("No book with this id, or an author id doesn't exist",
74
                bookNotFound, unknownAuthorOfBook))
75
            .addResponses(MALFORMED_AUTHOR_ID, response("The id is not a UUID", malformedAuthorId))
76
            .addResponses(INVALID_AUTHOR, response("The request body is invalid", invalidNewAuthor))
77
            .addResponses(INVALID_AUTHOR_OR_ID, response("The request body is invalid, or the id is not a UUID",
78
                invalidAuthor, malformedAuthorId))
79
            .addResponses(AUTHOR_NOT_FOUND, response("No author with this id", authorNotFound))
80
            .addResponses(AUTHOR_HAS_BOOKS, response("The author still has books", authorHasBooks));
81
    }
82

83
    // The fields ApiExceptionHandler's problems have; "errors" only on a failed validation.
84
    private static Schema<?> problemSchema() {
85
        return new ObjectSchema()
86
            .description("An RFC 9457 problem detail")
87
            .addProperty("detail", new StringSchema().description("What went wrong with this request"))
88
            .addProperty("instance", new StringSchema().description("The path of the request"))
89
            .addProperty("status", new IntegerSchema().description("The HTTP status code"))
90
            .addProperty("title", new StringSchema().description("A short summary of the kind of problem"))
91
            .addProperty("errors", new ObjectSchema()
92
                .additionalProperties(new StringSchema())
93
                .description("Only when validation failed: each invalid field and its message"));
94
    }
95

96
    // A response with a Problem body and the given examples, each named by its summary.
97
    private static ApiResponse response(String description, Example... examples) {
98
        MediaType problem = new MediaType().schema(new Schema<>().$ref("#/components/schemas/Problem"));
99
        for (Example example : examples) {
100
            problem.addExamples(example.getSummary(), example);
101
        }
102
        return new ApiResponse()
103
            .description(description)
104
            .content(new Content().addMediaType("application/problem+json", problem));
105
    }
106

107
    // An example problem with the given fields.
108
    private static Example problem(String summary, String detail, String instance, int status, String title) {
109
        return new Example().summary(summary).value(body(detail, instance, status, title));
110
    }
111

112
    // An example of a failed validation: ApiExceptionHandler's fixed detail and title, plus the field errors.
113
    private static Example invalid(String instance, Map<String, String> errors) {
114
        Map<String, Object> body = body("One or more fields are invalid.", instance, 400, "Validation failed");
115
        body.put("errors", errors);
116
        return new Example().summary("The request body is invalid").value(body);
117
    }
118

119
    // A problem body, its fields in the order the API sends them.
120
    private static Map<String, Object> body(String detail, String instance, int status, String title) {
121
        Map<String, Object> body = new LinkedHashMap<>();
122
        body.put("detail", detail);
123
        body.put("instance", instance);
124
        body.put("status", status);
125
        body.put("title", title);
126
        return body;
127
    }
128
}

OpenAPI components are the reusable parts of a spec — schemas, responses, examples — each under a name, and referred to elsewhere with a $ref ^[spec]. components() builds them with the same Java model as OpenApiConfig's Info: one schema, Problem, and eleven named responses.
Problem is the schema of the JSON, not of a Java class: detail, instance, status and title, which every error has, and errors, which only a failed validation adds. type isn't there because the API never sends it.
Each response is one operation's view of an error, because an operation can document only one response per status. PUT /api/books/{id} answers 400 for an invalid body and for an id that isn't a UUID, so InvalidBookOrId carries both examples; the docs page offers them by their summaries. GET and DELETE have no body, so they use MalformedBookId alone.
Every example was copied from a real response of the running app, with the field order the API uses and the same ids as the parameter and record examples. bookNotFound is the body above. They are kept honest by hand: change a message in ApiExceptionHandler or a service, and Lesson 11's and Lesson 13's tests fail and point at it, but this class needs the same edit.
The names are constants, so BookApi and AuthorApi refer to ProblemResponses.BOOK_NOT_FOUND rather than a string a typo could break. components() is package-private: only OpenApiConfig calls it.
LinkedHashMap keeps the keys in the order they are put, so each example lists its fields as the API sends them; Map.of would change the order from run to run.

OpenApiConfig adds the components to the spec:

1
package com.example.library.config;
2

3
import io.swagger.v3.oas.models.OpenAPI;
4
import io.swagger.v3.oas.models.info.Info;
5
import org.springframework.context.annotation.Bean;
6
import org.springframework.context.annotation.Configuration;
7

8
@Configuration(proxyBeanMethods = false)
9
public class OpenApiConfig {
10

11
    @Bean
12
    OpenAPI libraryOpenApi() {
13
        return new OpenAPI()
14
            .info(new Info()
15
                .title("Library API")
16
                .version("v1")
17
                .description("Books and their authors. Errors are RFC 9457 problem details (application/problem+json)."))
18
            .components(ProblemResponses.components());   // the error responses BookApi and AuthorApi refer to
19
    }
20
}

Step 4 — Document the book endpoints in an interface

The rest of the information is per endpoint, written with the annotations of the Swagger library (io.swagger.v3.oas.annotations) and one from springdoc. For one operation that is a summary, a description, three or four responses and a parameter description — more lines than the method itself. Put on the controller, it would bury the code a reader of BookController comes for.

So the documentation goes in an interface, BookApi, that BookController implements: the interface holds what the docs say, the controller what Spring MVC does. springdoc reads the annotations from the interface method a controller method implements ^[docs], so the spec comes out the same as if they were on the controller. Create it next to the controller:

1
package com.example.library.book;
2

3
import java.util.UUID;
4
import com.example.library.config.ProblemResponses;
5
import io.swagger.v3.oas.annotations.Operation;
6
import io.swagger.v3.oas.annotations.Parameter;
7
import io.swagger.v3.oas.annotations.responses.ApiResponse;
8
import io.swagger.v3.oas.annotations.tags.Tag;
9
import org.springdoc.core.annotations.ParameterObject;
10
import org.springframework.data.domain.Page;
11
import org.springframework.data.domain.Pageable;
12
import org.springframework.http.ResponseEntity;
13

14
// The book endpoints' API documentation. BookController implements it and keeps only the Spring MVC code.
15
@Tag(name = "Books", description = "Create, read, replace and delete books")
16
public interface BookApi {
17

18
    @Operation(summary = "List books", description = "A page of books, sorted by title unless `sort` says otherwise.")
19
    @ApiResponse(responseCode = "200", description = "A page of books")
20
    Page<BookResponse> all(
21
        @Parameter(description = "Only the books this author wrote or co-wrote", example = "01a125d2-f7d2-77d5-a5a7-945523ee5cc1")
22
        UUID authorId,
23
        @ParameterObject Pageable pageable);
24

25
    @Operation(summary = "Get a book")
26
    @ApiResponse(responseCode = "200", description = "The book")
27
    @ApiResponse(responseCode = "400", ref = ProblemResponses.MALFORMED_BOOK_ID)
28
    @ApiResponse(responseCode = "404", ref = ProblemResponses.BOOK_NOT_FOUND)
29
    BookResponse byId(@Parameter(description = "The book's id", example = "01a125d2-f80e-7ba4-aa2d-d296d723ecb7") UUID id);
30

31
    @Operation(summary = "Create a book", description = "Every author id must belong to an existing author.")
32
    @ApiResponse(responseCode = "201", description = "Created; the Location header holds the new book's URL")
33
    @ApiResponse(responseCode = "400", ref = ProblemResponses.INVALID_BOOK)
34
    @ApiResponse(responseCode = "404", ref = ProblemResponses.UNKNOWN_AUTHOR_ID)
35
    ResponseEntity<BookResponse> create(CreateBookRequest req);
36

37
    @Operation(summary = "Replace a book", description = "Sets the title, year and authors; authors left out are unlinked.")
38
    @ApiResponse(responseCode = "200", description = "The book as stored now")
39
    @ApiResponse(responseCode = "400", ref = ProblemResponses.INVALID_BOOK_OR_ID)
40
    @ApiResponse(responseCode = "404", ref = ProblemResponses.BOOK_OR_AUTHOR_NOT_FOUND)
41
    BookResponse replace(
42
        @Parameter(description = "The book's id", example = "01a125d2-f80e-7ba4-aa2d-d296d723ecb7") UUID id,
43
        CreateBookRequest req);
44

45
    @Operation(summary = "Delete a book", description = "Its authors stay.")
46
    @ApiResponse(responseCode = "204", description = "Deleted")
47
    @ApiResponse(responseCode = "400", ref = ProblemResponses.MALFORMED_BOOK_ID)
48
    @ApiResponse(responseCode = "404", ref = ProblemResponses.BOOK_NOT_FOUND)
49
    void delete(@Parameter(description = "The book's id", example = "01a125d2-f80e-7ba4-aa2d-d296d723ecb7") UUID id);
50
}

@Tag names the group on the docs page — "Books" instead of book-controller — and describes it.
@Operation gives each operation a summary, the one-liner shown in the sidebar, and an optional longer description. The descriptions say what the signature can't: which order a list comes in, that a PUT unlinks the authors left out, that deleting a book leaves its authors.
@ApiResponse, one per status the operation can answer with. Once an operation declares any, springdoc documents exactly those. A success response without content still gets its body schema from the return type, so 201 is listed with BookResponse. An error response is a ref to one of Step 3's named responses — schema, description and examples included — so each is one line. Every operation with an id in its path also lists the 400 for an id that isn't a UUID, which Lesson 11's controller tests already check.
@ParameterObject tells springdoc to document the fields of Pageable as separate query parameters, which is how Spring binds them ^[docs].
@Parameter describes a path or query parameter; its type and format (string, uuid) springdoc already knew. The example is the id the docs page puts into the request it shows. The ids match the ones in Step 3's error examples and in the records' examples in Step 5, so the examples tell one consistent story.
The interface has no Spring MVC annotations, no paths, no @PathVariable: those stay on the controller, where Spring reads them. An interface method is abstract, so the interface is nothing but signatures and their documentation.

BookController then changes in two ways only: it implements BookApi, and each handler method is marked @Override:


24 collapsed lines
1
package com.example.library.book;
2

3
import java.net.URI;
4
import java.util.UUID;
5
import jakarta.validation.Valid;
6
import com.example.library.util.Pageables;
7
import org.springframework.data.domain.Page;
8
import org.springframework.data.domain.Pageable;
9
import org.springframework.data.web.PageableDefault;
10
import org.springframework.http.HttpStatus;
11
import org.springframework.http.ResponseEntity;
12
import org.springframework.web.bind.annotation.DeleteMapping;
13
import org.springframework.web.bind.annotation.GetMapping;
14
import org.springframework.web.bind.annotation.PathVariable;
15
import org.springframework.web.bind.annotation.PostMapping;
16
import org.springframework.web.bind.annotation.PutMapping;
17
import org.springframework.web.bind.annotation.RequestBody;
18
import org.springframework.web.bind.annotation.RequestMapping;
19
import org.springframework.web.bind.annotation.RequestParam;
20
import org.springframework.web.bind.annotation.ResponseStatus;
21
import org.springframework.web.bind.annotation.RestController;
22

23
@RestController
24
@RequestMapping("/api/books")
25
public class BookController implements BookApi {
26

5 collapsed lines
27
    private final BookService books;
28

29
    public BookController(BookService books) {
30
        this.books = books;
31
    }
32

33
    @Override
34
    @GetMapping                                          // GET /api/books?authorId=...&page=0&size=20&sort=title
35
    public Page<BookResponse> all(
36
            @RequestParam(required = false) UUID authorId,
37
            @PageableDefault(size = 20, sort = "title") Pageable pageable) {
38
        return books.findAll(authorId, Pageables.withIdTiebreaker(pageable)).map(BookResponse::from);
39
    }
40

41
    @Override
42
    @GetMapping("/{id}")
43
    public BookResponse byId(@PathVariable UUID id) {
44
        return BookResponse.from(books.getById(id));
45
    }
46

47
    @Override
48
    @PostMapping                                         // POST /api/books
49
    public ResponseEntity<BookResponse> create(@Valid @RequestBody CreateBookRequest req) {
50
        Book saved = books.create(req.title(), req.year(), req.authorIds());
51
        URI location = URI.create("/api/books/" + saved.getId());
52
        return ResponseEntity.created(location).body(BookResponse.from(saved));
53
    }
54

55
    @Override
56
    @PutMapping("/{id}")                                 // PUT /api/books/{id}
57
    public BookResponse replace(@PathVariable UUID id, @Valid @RequestBody CreateBookRequest req) {
58
        return BookResponse.from(books.replace(id, req.title(), req.year(), req.authorIds()));
59
    }
60

61
    @Override
62
    @DeleteMapping("/{id}")                              // DELETE /api/books/{id}
63
    @ResponseStatus(HttpStatus.NO_CONTENT)               // 204 on success
64
    public void delete(@PathVariable UUID id) {
65
        books.delete(id);                                // throws NotFoundException -> 404
66
    }
67
}

springdoc reads both files. The documentation comes from BookApi; the paths, the parameter bindings and @PageableDefault come from the controller — so the docs still show the default size of 20 and the sort by title.
@Override keeps the two in step. Change a method's signature in one file and not the other, and the code no longer compiles, instead of the docs quietly describing a method that is gone.
The controller's behaviour doesn't change, and Lesson 11's controller tests run against it unchanged.

Step 5 — Describe the book records

The schemas come from the records themselves, so their documentation stays on them: @Schema on the record describes the whole object; on a component, that field — with an example, which the docs page uses in the requests and responses it shows:

1
package com.example.library.book;
2

3
import java.util.Set;
4
import java.util.UUID;
5
import io.swagger.v3.oas.annotations.media.Schema;
6
import jakarta.validation.constraints.NotBlank;
7
import jakarta.validation.constraints.NotEmpty;
8
import jakarta.validation.constraints.Positive;
9

10
@Schema(description = "A book to create, or the new state of an existing one")
11
public record CreateBookRequest(
12
    @Schema(description = "The book's title", example = "The Pragmatic Programmer")
13
    @NotBlank String title,          // not null, and not just whitespace
14
    @Schema(description = "Year of publication", example = "1999")
15
    @Positive int year,              // must be > 0
16
    @Schema(description = "Ids of the book's authors; each must exist", example = "[\"01a125d2-f7d2-77d5-a5a7-945523ee5cc1\"]")
17
    @NotEmpty Set<UUID> authorIds    // at least one author
18
) {}

1
package com.example.library.book;
2

3
import java.util.Comparator;
4
import java.util.List;
5
import java.util.UUID;
6
import com.example.library.author.AuthorResponse;
7
import io.swagger.v3.oas.annotations.media.Schema;
8

9
// What we SEND BACK. Authors as a list, sorted by name so the JSON order is stable.
10
@Schema(description = "A book with its authors")
11
public record BookResponse(
12
    @Schema(description = "The book's id, a UUIDv7", example = "01a125d2-f80e-7ba4-aa2d-d296d723ecb7") UUID id,
13
    @Schema(description = "The book's title", example = "The Pragmatic Programmer") String title,
14
    @Schema(description = "Year of publication", example = "1999") int year,
15
    @Schema(description = "The book's authors, sorted by name") List<AuthorResponse> authors) {
16
    public static BookResponse from(Book book) {
17
        List<AuthorResponse> authors = book.getAuthors().stream()
18
            .map(AuthorResponse::from)
19
            .sorted(Comparator.comparing(AuthorResponse::name))
20
            .toList();
21
        return new BookResponse(book.getId(), book.getTitle(), book.getYear(), authors);
22
    }
23
}

The constraints stay where they were. @NotBlank, @Positive and @NotEmpty already reach the spec — as minLength, exclusiveMinimum and minItems — so @Schema doesn't repeat them; it only adds the words.
An example must be valid JSON for the field's type, written as a Java string. A number is "1999"; an array is the JSON text ["…"], with its quotes escaped.
BookResponse's components carry their annotations in front of each, which is why the record header now spans several lines. The from method is unchanged.

Step 6 — The author endpoints and records

The same for authors. AuthorApi first:

1
package com.example.library.author;
2

3
import java.util.UUID;
4
import com.example.library.config.ProblemResponses;
5
import io.swagger.v3.oas.annotations.Operation;
6
import io.swagger.v3.oas.annotations.Parameter;
7
import io.swagger.v3.oas.annotations.responses.ApiResponse;
8
import io.swagger.v3.oas.annotations.tags.Tag;
9
import org.springdoc.core.annotations.ParameterObject;
10
import org.springframework.data.domain.Page;
11
import org.springframework.data.domain.Pageable;
12
import org.springframework.http.ResponseEntity;
13

14
// The author endpoints' API documentation. AuthorController implements it and keeps only the Spring MVC code.
15
@Tag(name = "Authors", description = "Create, read, replace and delete authors")
16
public interface AuthorApi {
17

18
    @Operation(summary = "List authors", description = "A page of authors, sorted by name unless `sort` says otherwise.")
19
    @ApiResponse(responseCode = "200", description = "A page of authors")
20
    Page<AuthorResponse> all(@ParameterObject Pageable pageable);
21

22
    @Operation(summary = "Get an author")
23
    @ApiResponse(responseCode = "200", description = "The author")
24
    @ApiResponse(responseCode = "400", ref = ProblemResponses.MALFORMED_AUTHOR_ID)
25
    @ApiResponse(responseCode = "404", ref = ProblemResponses.AUTHOR_NOT_FOUND)
26
    AuthorResponse byId(@Parameter(description = "The author's id", example = "01a125d2-f7d2-77d5-a5a7-945523ee5cc1") UUID id);
27

28
    @Operation(summary = "Create an author")
29
    @ApiResponse(responseCode = "201", description = "Created; the Location header holds the new author's URL")
30
    @ApiResponse(responseCode = "400", ref = ProblemResponses.INVALID_AUTHOR)
31
    ResponseEntity<AuthorResponse> create(CreateAuthorRequest req);
32

33
    @Operation(summary = "Replace an author")
34
    @ApiResponse(responseCode = "200", description = "The author as stored now")
35
    @ApiResponse(responseCode = "400", ref = ProblemResponses.INVALID_AUTHOR_OR_ID)
36
    @ApiResponse(responseCode = "404", ref = ProblemResponses.AUTHOR_NOT_FOUND)
37
    AuthorResponse replace(
38
        @Parameter(description = "The author's id", example = "01a125d2-f7d2-77d5-a5a7-945523ee5cc1") UUID id,
39
        CreateAuthorRequest req);
40

41
    @Operation(summary = "Delete an author", description = "Only an author with no books can be deleted.")
42
    @ApiResponse(responseCode = "204", description = "Deleted")
43
    @ApiResponse(responseCode = "400", ref = ProblemResponses.MALFORMED_AUTHOR_ID)
44
    @ApiResponse(responseCode = "404", ref = ProblemResponses.AUTHOR_NOT_FOUND)
45
    @ApiResponse(responseCode = "409", ref = ProblemResponses.AUTHOR_HAS_BOOKS)
46
    void delete(@Parameter(description = "The author's id", example = "01a125d2-f7d2-77d5-a5a7-945523ee5cc1") UUID id);
47
}

Only DELETE can answer 409, the one Lesson 7's conflict rule produces, so only DELETE declares it. AuthorController implements it, the same two changes as BookController:


23 collapsed lines
1
package com.example.library.author;
2

3
import java.net.URI;
4
import java.util.UUID;
5
import jakarta.validation.Valid;
6
import com.example.library.util.Pageables;
7
import org.springframework.data.domain.Page;
8
import org.springframework.data.domain.Pageable;
9
import org.springframework.data.web.PageableDefault;
10
import org.springframework.http.HttpStatus;
11
import org.springframework.http.ResponseEntity;
12
import org.springframework.web.bind.annotation.DeleteMapping;
13
import org.springframework.web.bind.annotation.GetMapping;
14
import org.springframework.web.bind.annotation.PathVariable;
15
import org.springframework.web.bind.annotation.PostMapping;
16
import org.springframework.web.bind.annotation.PutMapping;
17
import org.springframework.web.bind.annotation.RequestBody;
18
import org.springframework.web.bind.annotation.RequestMapping;
19
import org.springframework.web.bind.annotation.ResponseStatus;
20
import org.springframework.web.bind.annotation.RestController;
21

22
@RestController
23
@RequestMapping("/api/authors")
24
public class AuthorController implements AuthorApi {
25

5 collapsed lines
26
    private final AuthorService authors;
27

28
    public AuthorController(AuthorService authors) {
29
        this.authors = authors;
30
    }
31

32
    @Override
33
    @GetMapping                                          // GET /api/authors?page=0&size=20&sort=name
34
    public Page<AuthorResponse> all(@PageableDefault(size = 20, sort = "name") Pageable pageable) {
35
        return authors.findAll(Pageables.withIdTiebreaker(pageable)).map(AuthorResponse::from);
36
    }
37

38
    @Override
39
    @GetMapping("/{id}")
40
    public AuthorResponse byId(@PathVariable UUID id) {
41
        return AuthorResponse.from(authors.getById(id));
42
    }
43

44
    @Override
45
    @PostMapping
46
    public ResponseEntity<AuthorResponse> create(@Valid @RequestBody CreateAuthorRequest req) {
47
        Author saved = authors.create(req.name());
48
        URI location = URI.create("/api/authors/" + saved.getId());
49
        return ResponseEntity.created(location).body(AuthorResponse.from(saved));
50
    }
51

52
    @Override
53
    @PutMapping("/{id}")
54
    public AuthorResponse replace(@PathVariable UUID id, @Valid @RequestBody CreateAuthorRequest req) {
55
        return AuthorResponse.from(authors.replace(id, req.name()));
56
    }
57

58
    @Override
59
    @DeleteMapping("/{id}")
60
    @ResponseStatus(HttpStatus.NO_CONTENT)               // 204 on success
61
    public void delete(@PathVariable UUID id) {
62
        authors.delete(id);                              // NotFoundException -> 404, ConflictException -> 409
63
    }
64
}

And the two records:

1
package com.example.library.author;
2

3
import io.swagger.v3.oas.annotations.media.Schema;
4
import jakarta.validation.constraints.NotBlank;
5

6
@Schema(description = "An author to create, or the new state of an existing one")
7
public record CreateAuthorRequest(
8
    @Schema(description = "The author's name", example = "Andrew Hunt") @NotBlank String name) {}

1
package com.example.library.author;
2

3
import java.util.UUID;
4
import io.swagger.v3.oas.annotations.media.Schema;
5

6
// What we SEND BACK for an author - on its own, or nested inside a book.
7
@Schema(description = "An author")
8
public record AuthorResponse(
9
    @Schema(description = "The author's id, a UUIDv7", example = "01a125d2-f7d2-77d5-a5a7-945523ee5cc1") UUID id,
10
    @Schema(description = "The author's name", example = "Andrew Hunt") String name) {
11
    public static AuthorResponse from(Author author) {
12
        return new AuthorResponse(author.getId(), author.getName());
13
    }
14
}

The reference describes each endpoint on its own. What they have in common — how to get started, what an id is, how paging works, what an error looks like — has no endpoint to live on, and a client developer needs it before the list makes sense.

That goes in a short guide, written by hand in Markdown, kept in the project next to the code and served as the API's description. The spec's description is Markdown ^[spec], and Scalar shows it at the top of the page, with each ## heading as its own entry in the sidebar. Create src/main/resources/api-guide.md:

Books and their authors, as a JSON API. The sidebar lists every endpoint; this guide covers what they have in common.

## Getting started

The API runs on `http://localhost:8080`. Create an author:

```bash
curl -i -X POST http://localhost:8080/api/authors \
  -H 'Content-Type: application/json' \
  -d '{"name": "Andrew Hunt"}'
```

The answer is `201 Created`: the new author in the body, its address in the `Location` header. Create a book by that author, with the `id` from the body:

```bash
curl -i -X POST http://localhost:8080/api/books \
  -H 'Content-Type: application/json' \
  -d '{"title": "The Pragmatic Programmer", "year": 1999, "authorIds": ["<the author id>"]}'
```

Then list the books:

```bash
curl http://localhost:8080/api/books
```

## Ids

Books and authors are identified by UUIDs, version 7, which the API creates. A request body never carries an id: a `POST` returns the new one, in the body and in the `Location` header.

## Paging and sorting

`GET /api/books` and `GET /api/authors` return one page at a time, as `{ "content": [...], "page": {...} }`, where `page` holds `size`, `number`, `totalElements` and `totalPages`. Three query parameters choose the page:

| Parameter | Meaning | Default |
| --- | --- | --- |
| `page` | Page number, starting at 0 | `0` |
| `size` | Items per page; more than 100 counts as 100 | `20` |
| `sort` | `property,asc` or `property,desc`; repeat it to sort by several | `title` (books), `name` (authors) |

Items that sort equal are ordered by id, so the pages of a list never overlap.

## Errors

Every error is an RFC 9457 problem detail, `application/problem+json`, with `detail`, `instance`, `status` and `title`:

| Status | When |
| --- | --- |
| `400` | The request body is invalid (the body then has an `errors` object: field name to message), or an id in the path isn't a UUID |
| `404` | No book or author with that id, or a book names an author id that doesn't exist |
| `409` | An author can't be deleted while they still have books |

Each operation lists the errors it can return, with an example of each.

Every sentence is about this API and comes from an earlier lesson: the 201 and Location from Lesson 4, the server-made UUIDv7 ids from Lesson 5, the page shape, the cap of 100 and the id tie-breaker from Lesson 8, the errors from Lesson 7. The guide links them together for someone who has read none of those.
The Getting started commands are the shortest real session: an author, a book by them, the list. <the author id> is the one place a reader has to fill in.
The file lives in src/main/resources, so it is packed into the app, and it changes in the same commit as the code it describes. Markdown tables and fenced code blocks render as they do on GitHub.

OpenApiConfig reads it as the description, in place of the one line it had:

1
package com.example.library.config;
2

3
import java.io.IOException;
4
import java.nio.charset.StandardCharsets;
5
import io.swagger.v3.oas.models.OpenAPI;
6
import io.swagger.v3.oas.models.info.Info;
7
import org.springframework.context.annotation.Bean;
8
import org.springframework.context.annotation.Configuration;
9
import org.springframework.core.io.ClassPathResource;
10

11
@Configuration(proxyBeanMethods = false)
12
public class OpenApiConfig {
13

14
    @Bean
15
    OpenAPI libraryOpenApi() throws IOException {
16
        return new OpenAPI()
17
            .info(new Info()
18
                .title("Library API")
19
                .version("v1")
20
                .description(new ClassPathResource("api-guide.md").getContentAsString(StandardCharsets.UTF_8)))
21
            .components(ProblemResponses.components());   // the error responses BookApi and AuthorApi refer to
22
    }
23
}

ClassPathResource("api-guide.md") finds the file on the classpath, where Maven copies everything from src/main/resources — in the IDE, in ./mvnw spring-boot:run and inside a packaged jar alike ^[docs]. getContentAsString reads it whole.
throws IOException: a missing or unreadable guide fails the bean, so the app doesn't start — the mistake shows up at once, not as empty docs.

Step 8 — Look again

Start the app again:

./mvnw spring-boot:run

Reload http://localhost:8080/scalar. The page is titled "Library API" with the guide below it, and the sidebar starts with the guide's sections — "Getting started", "Ids", "Paging and sorting", "Errors" — then groups the endpoints under "Books" and "Authors", each by its summary; open "Create a book" and the body fields carry their descriptions, the responses list 201, 400 and 404, and the curl command on the right sends the example body; switch the example on the right to 404 and it shows the body the API really sends. The info, the /api/books path and one of the shared responses in http://localhost:8080/v3/api-docs now:

"info": {
  "title": "Library API",
  "description": "Books and their authors, as a JSON API. The sidebar lists every endpoint; this guide covers what they have in common.\n\n## Getting started\n\nThe API runs on …",
  "version": "v1"
},
…
"/api/books": {
  "get": {
    "tags": [
      "Books"
    ],
    "summary": "List books",
    "description": "A page of books, sorted by title unless `sort` says otherwise.",
    "operationId": "all",
    "parameters": [
      {
        "name": "authorId",
        "in": "query",
        "description": "Only the books this author wrote or co-wrote",
        "required": false,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "example": "01a125d2-f7d2-77d5-a5a7-945523ee5cc1"
      },
      {
        "name": "page",
        "in": "query",
        "description": "Zero-based page index (0..N)",
        "required": false,
        "schema": {
          "type": "integer",
          "default": 0,
          "minimum": 0
        }
      },
      {
        "name": "size",
        "in": "query",
        "description": "The size of the page to be returned",
        "required": false,
        "schema": {
          "type": "integer",
          "default": 20,
          "minimum": 1
        }
      },
      {
        "name": "sort",
        "in": "query",
        "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
        "required": false,
        "schema": {
          "type": "array",
          "default": [
            "title,ASC"
          ],
          "items": {
            "type": "string"
          }
        }
      }
    ],
    "responses": {
      "200": { … }
    }
  },
  "post": {
    "tags": [
      "Books"
    ],
    "summary": "Create a book",
    "description": "Every author id must belong to an existing author.",
    "operationId": "create",
    "requestBody": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateBookRequest"
          }
        }
      },
      "required": true
    },
    "responses": {
      "201": {
        "description": "Created; the Location header holds the new book's URL",
        "content": {
          "*/*": {
            "schema": {
              "$ref": "#/components/schemas/BookResponse"
            }
          }
        }
      },
      "400": {
        "$ref": "#/components/responses/InvalidBook"
      },
      "404": {
        "$ref": "#/components/responses/UnknownAuthorId"
      }
    }
  }
},
…
"UnknownAuthorId": {
  "description": "An author id doesn't exist",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/Problem"
      },
      "examples": {
        "An author id doesn't exist": {
          "summary": "An author id doesn't exist",
          "value": {
            "detail": "No author with id [01a125d2-f7d2-77d5-a5a7-945523ee5cc1]",
            "instance": "/api/books",
            "status": 404,
            "title": "Resource not found"
          }
        }
      }
    }
  }
}
…

Compared with Step 1: the title and version are the API's own, and the description is the guide, one long Markdown string; the tag is Books; authorId has its description and example; page, size and sort are three optional parameters, with the defaults from the controller's @PageableDefault — size 20, sort title,ASC — and springdoc's own descriptions; POST answers 201, and its 400 and 404 are references to two of Step 3's shared responses. The last part is one of them, under components: the Problem schema and the example, the same body POST /api/books returns for an author that doesn't exist. The words came from BookApi, ProblemResponses and OpenApiConfig; the paths and defaults from the controller. The record schemas, further down, now carry the descriptions and examples from @Schema.

Stop the app with Ctrl+C.

Who sees the docs?

Anyone who can reach the app can read /v3/api-docs and open /scalar, in production too. For a public API that is the point. For an internal one you may not want to publish its map: springdoc.api-docs.enabled=false switches the spec off ^[docs] and scalar.enabled=false the page, typically in the configuration of the environments where they shouldn't be. The Library API keeps them on.

Step 9 — Make the docs page the app's own

Open your browser's developer tools on http://localhost:8080/scalar, switch to the Network tab and reload. Besides the app's own /scalar/scalar.js and /v3/api-docs, the page talks to Scalar's servers: it loads its fonts from fonts.scalar.com, and it fetches a list of public APIs through proxy.scalar.com. That list belongs to two extras in the page's header:

"Ask AI" is Scalar's hosted AI chat. On localhost it is on by default with a few free messages; anywhere else it needs a paid key ^[docs]. Using it means your spec and your questions go to Scalar's servers — fine for a public API, not something to offer by accident for an internal one.
"Developer Tools" is a toolbar for changing the page's look and publishing the docs to Scalar's registry. It only appears when the page runs on localhost.

The page also carries Scalar's name instead of the API's: it lives at /scalar, a path named after the tool, and the browser tab says "Scalar API Reference". A client shouldn't need to know which tool renders the docs; /docs says what is there.

The docs page is self-contained: no AI chat, no developer toolbar, no separate API client, and its fonts served by the app itself, so nothing about the API leaves the app and the page doesn't depend on anyone else's servers to look right. Both fonts, Inter and JetBrains Mono, are open source under the SIL Open Font License, which allows shipping them with your app as long as the license goes with them.

Download them from their projects' official releases into src/main/resources/static/fonts/, each with its license. Run this from the project directory (the Inter archive is about 34 MB):

mkdir -p src/main/resources/static/fonts
curl -L -o /tmp/inter.zip https://github.com/rsms/inter/releases/download/v4.1/Inter-4.1.zip
unzip -j /tmp/inter.zip web/InterVariable.woff2 -d src/main/resources/static/fonts
unzip -p /tmp/inter.zip LICENSE.txt > src/main/resources/static/fonts/Inter-LICENSE.txt
curl -L -o /tmp/jetbrains-mono.zip https://github.com/JetBrains/JetBrainsMono/releases/download/v2.304/JetBrainsMono-2.304.zip
unzip -j /tmp/jetbrains-mono.zip fonts/webfonts/JetBrainsMono-Regular.woff2 -d src/main/resources/static/fonts
unzip -p /tmp/jetbrains-mono.zip OFL.txt > src/main/resources/static/fonts/JetBrainsMono-LICENSE.txt

unzip -j extracts the one file named after the archive, without the folders it sits in (web/, fonts/webfonts/); unzip -p prints a file instead, here into the license file next to the font.
InterVariable.woff2 is Inter as a variable font: one file with every weight from 100 to 900, which is how Scalar uses it. Of JetBrains Mono, Scalar uses only the regular weight.
Spring Boot serves everything under src/main/resources/static/ as it is, at the root of the app ^[docs]: the fonts will be at /fonts/InterVariable.woff2 and /fonts/JetBrainsMono-Regular.woff2.

Then seven settings at the end of application.properties:


13 collapsed lines
1
# Hibernate never alters the schema - Liquibase owns it. Just verify entities match the tables.
2
spring.jpa.hibernate.ddl-auto=validate
3

4
# Render Page results in the stable { content, page } shape (PagedModel) instead of raw PageImpl
5
spring.data.web.pageable.serialization-mode=via_dto
6

7
# Cap how many rows one page request can pull
8
spring.data.web.pageable.max-page-size=100
9
# (optional) change the default page size for unparameterized requests
10
spring.data.web.pageable.default-page-size=20
11

12
# Close the session at the end of the service layer, not the end of the request
13
spring.jpa.open-in-view=false
14

15
# Docs page (Scalar) at /docs, titled after the API
16
scalar.path=/docs
17
scalar.page-title=Library API
18
# No AI chat - it would send the spec to Scalar's servers - and no developer toolbar
19
scalar.agent.disabled=true
20
scalar.show-developer-tools=never
21
# No separate API client: each operation's Test Request button is enough
22
scalar.hide-client-button=true
23
# Fonts from the app itself (static/fonts), not from Scalar's font server; no "Powered by Scalar" link
24
scalar.with-default-fonts=false
25
scalar.custom-css=\
26
  @font-face { font-family: "Inter"; font-weight: 100 900; font-display: swap; src: url(/fonts/InterVariable.woff2) format("woff2"); } \
27
  @font-face { font-family: "JetBrains Mono"; font-weight: 400; font-display: swap; src: url(/fonts/JetBrainsMono-Regular.woff2) format("woff2"); } \
28
  a[href="https://www.scalar.com"] { display: none; }

scalar.* are Scalar's own settings, which springdoc's module passes to the page ^[docs]. path moves the page, and its script with it, to /docs; /scalar then answers 404. page-title is the text in the browser tab. The spec stays at /v3/api-docs, springdoc's standard address, which tools and the test in Step 10 expect. agent.disabled removes the chat, and with it the list of public APIs the page fetched; show-developer-tools=never hides the toolbar on localhost too.
hide-client-button=true removes the "Open API Client" button at the bottom of the sidebar, which opens a whole request workspace for the API inside the page. Trying an endpoint is what the docs page is for, and each operation's own "Test Request" button, which stays, does exactly that.
with-default-fonts=false stops Scalar loading its fonts from its own server. On its own, the page would then fall back to whatever fonts the machine has.
custom-css adds CSS to the page. The two @font-face rules declare the same font families Scalar's styles ask for, "Inter" and "JetBrains Mono", but with files from /fonts/ — so the page looks exactly as before. The last rule hides the "Powered by Scalar" link at the bottom of the sidebar. Scalar has no setting for it, so the rule targets the link itself; a Scalar upgrade that changes the link would bring it back. Scalar's MIT license asks for its license text to travel with copies of the code, not for a credit on the page ^[license].
The trailing \ continues a value on the next line in a .properties file; the spaces at the start of the next line are dropped ^[docs]. The CSS stays one value, just readable.

Restart the app (./mvnw spring-boot:run) and open the page at its new address, http://localhost:8080/docs, with the Network tab open. The tab reads "Library API", and every request goes to localhost:8080: the page, /docs/scalar.js, /v3/api-docs and the two font files. "Ask AI" and "Developer Tools" are gone from the header, "Open API Client" and "Powered by Scalar" from the sidebar, and the text looks as it did. Stop the app with Ctrl+C.

Step 10 — A test for the docs

The spec is produced at runtime. Nothing at startup checks it: if a future springdoc and Spring Boot stop getting along, the app starts fine and the docs endpoint answers 500. And an annotation removed by accident — a @ParameterObject, an @ApiResponse — makes the docs wrong without breaking anything else.

So one integration test asks for the spec and checks what the annotations put there. It goes in the base test package, next to Lesson 13's:

1
package com.example.library;
2

3
import java.util.List;
4
import org.junit.jupiter.api.DisplayName;
5
import org.junit.jupiter.api.Test;
6
import org.springframework.beans.factory.annotation.Autowired;
7
import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureRestTestClient;
8
import org.springframework.boot.test.context.SpringBootTest;
9
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
10
import org.springframework.context.annotation.Import;
11
import org.springframework.test.web.servlet.client.RestTestClient;
12

13
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)   // the same three annotations as LibraryApiIntegrationTest,
14
@AutoConfigureRestTestClient                                   // so both classes share one cached context
15
@Import(TestcontainersConfiguration.class)
16
class ApiDocsIntegrationTest {
17

18
    @Autowired RestTestClient client;
19

20
    @Test
21
    @DisplayName("/v3/api-docs serves the spec, with what the code alone can't say")
22
    void apiDocs() {
23
        client.get().uri("/v3/api-docs")
24
            .exchange()
25
            .expectStatus().isOk()
26
            .expectBody()
27
            .jsonPath("$.info.title").isEqualTo("Library API")
28
            .jsonPath("$.paths['/api/books'].post.responses['201']").exists()
29
            .jsonPath("$.paths['/api/books'].get.parameters[*].name").isEqualTo(List.of("authorId", "page", "size", "sort"))
30
            .jsonPath("$.paths['/api/authors/{id}'].delete.responses['409']['$ref']").isEqualTo("#/components/responses/AuthorHasBooks")
31
            .jsonPath("$.components.responses.AuthorHasBooks.content['application/problem+json'].examples").exists();
32
    }
33
}

The same three annotations as LibraryApiIntegrationTest, exactly. That is Lesson 13's context caching put to use: the two classes have the same configuration, so they share one application context, one server and one PostgreSQL container, and this test costs no start-up of its own.
jsonPath(...) picks one value out of the response body with a JSONPath expression and checks it ^[docs]. Keys with / or { in them go in brackets: $.paths['/api/authors/{id}']. [*].name collects the name of every parameter, in order.
Each check is one claim the code makes: the title from OpenApiConfig, the 201 from @ApiResponse, the paging parameters from @ParameterObject, and the 409 — a reference to AuthorHasBooks, which exists in the components with its example. A name constant that components() forgets to register still compiles, and leaves a $ref in the spec that points nowhere; the last two checks would catch that for this response.

Why not compare the whole spec strictly?

Lesson 11 and Lesson 13 compare every response body in full, because the body is the API's contract and every byte of it is the application's. The spec is different: it is hundreds of lines, and much of its exact text is springdoc's — the order of the paths, the descriptions it writes for page and size, the schema of ProblemDetail — and changes with springdoc versions. A strict comparison would fail on each upgrade for reasons that aren't regressions. The test checks the claims the code makes and leaves the rest to springdoc.

Run it:

./mvnw test -Dtest=ApiDocsIntegrationTest

[INFO] Running com.example.library.ApiDocsIntegrationTest
…
2026-10-11T20:07:13.904Z  INFO 60040 --- [           main] c.e.library.ApiDocsIntegrationTest       : Started ApiDocsIntegrationTest in 17.773 seconds (process running for 20.039)
2026-10-11T20:07:14.999Z  WARN 60040 --- [           main] o.s.core.events.SpringDocAppInitializer  : SpringDoc /v3/api-docs endpoint is enabled by default. To disable it in production, set the property 'springdoc.api-docs.enabled=false'
2026-10-11T20:07:14.999Z  WARN 60040 --- [           main] o.s.core.events.SpringDocAppInitializer  : SpringDoc /docs endpoint is enabled by default. To disable it in production, set the property 'scalar.enabled=false'
…
2026-10-11T20:07:17.191Z  INFO 60040 --- [o-auto-1-exec-1] o.springdoc.api.AbstractOpenApiResource  : Init duration for springdoc-openapi is: 1035 ms
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 22.43 s -- in com.example.library.ApiDocsIntegrationTest
…
[INFO] BUILD SUCCESS

The two WARN lines are springdoc's own reminder of the callout above: both endpoints are on unless a property turns them off.
Init duration for springdoc-openapi shows when the spec is built. Look at its place and its thread. It comes after Started ApiDocsIntegrationTest, so startup was already over, and it runs on o-auto-1-exec-1, a Tomcat thread handling a request, as in Lesson 13. springdoc doesn't build the spec at startup: it builds it the first time someone asks for /v3/api-docs — here, the test — and keeps it for the requests after that ^[docs]. That is what the start of this step relies on: an app whose spec can't be built still starts, and only a request for the docs finds out.

Now make it fail the way it is meant to. In BookApi, delete @ParameterObject from the all method's pageable parameter (leave the import), and run the test again:

./mvnw test -Dtest=ApiDocsIntegrationTest

[ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 21.91 s <<< FAILURE! -- in com.example.library.ApiDocsIntegrationTest
[ERROR] com.example.library.ApiDocsIntegrationTest.apiDocs -- Time elapsed: 2.010 s <<< FAILURE!
java.lang.AssertionError: JSON path "$.paths['/api/books'].get.parameters[*].name" expected:<[authorId, page, size, sort]> but was:<[authorId, pageable]>
…
  at com.example.library.ApiDocsIntegrationTest.apiDocs(ApiDocsIntegrationTest.java:29)
…
[INFO] BUILD FAILURE

The app compiles, starts and serves every request as before — only the docs went back to Step 1's single pageable object, and the message says exactly that, path and both values.

Put @ParameterObject back.

Step 11 — Run it

Run the whole suite:

./mvnw test

[INFO] Running com.example.library.LibraryApiIntegrationTest
…
2026-10-11T20:08:11.516Z  INFO 61246 --- [           main] tc.postgres:18                           : Container postgres:18 started in PT1.494773987S
…
2026-10-11T20:08:18.946Z  INFO 61246 --- [           main] c.e.library.LibraryApiIntegrationTest    : Started LibraryApiIntegrationTest in 14.307 seconds (process running for 16.385)
…
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 17.77 s -- in com.example.library.LibraryApiIntegrationTest
[INFO] Running com.example.library.author.AuthorControllerTest
…
[INFO] Tests run: 12, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.064 s -- in com.example.library.author.AuthorControllerTest
[INFO] Running com.example.library.author.AuthorServiceTest
[INFO] Tests run: 9, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.545 s -- in com.example.library.author.AuthorServiceTest
[INFO] Running com.example.library.ApiDocsIntegrationTest
…
2026-10-11T20:08:26.165Z  INFO 61246 --- [o-auto-1-exec-5] o.springdoc.api.AbstractOpenApiResource  : Init duration for springdoc-openapi is: 866 ms
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.100 s -- in com.example.library.ApiDocsIntegrationTest
[INFO] Running com.example.library.book.BookControllerTest
…
[INFO] Tests run: 10, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.156 s -- in com.example.library.book.BookControllerTest
[INFO] Running com.example.library.book.BookServiceTest
[INFO] Tests run: 11, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.059 s -- in com.example.library.book.BookServiceTest
[INFO] Running com.example.library.book.BookRepositoryTest
…
[INFO] Tests run: 9, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.272 s -- in com.example.library.book.BookRepositoryTest
[INFO] Running com.example.library.LibraryApplicationTests
…
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.623 s -- in com.example.library.LibraryApplicationTests
…
[INFO] Tests run: 56, Failures: 0, Errors: 0, Skipped: 0
…
[INFO] BUILD SUCCESS

56 tests, all green, one more than Lesson 13. As before, your total may be smaller if you skipped Lesson 10's exercises.
ApiDocsIntegrationTest has no Started line and took about a second: it ran in the context LibraryApiIntegrationTest had already started — same server, same container.
The controller tests are unchanged and green. The controllers now implement an interface; what they do is the same.

If it doesn't behave

The docs page is a 404? Until Step 9 it is at /scalar, from then on at /docs. If neither answers, check the dependency: it is springdoc-openapi-starter-webmvc-scalar; the -ui artifact serves Swagger UI at /swagger-ui.html instead, and the -api artifact serves only the spec. Re-run ./mvnw spring-boot:run after changing pom.xml.
The docs page doesn't show your endpoints? It renders whatever /v3/api-docs returns. Open http://localhost:8080/v3/api-docs directly; if it answers with an error, the exception that broke the spec is in the app's console.

Check yourself

Answer from memory before revealing.

Where does springdoc-openapi get the API description from?

Why did the generated spec document POST /api/books as 200?

What does @ParameterObject change for the Pageable parameter?

Why are the error responses declared on each operation by hand?

Why does ProblemResponses define a Problem schema instead of using ProblemDetail?

How does springdoc document BookController.byId when its annotations are in BookApi?

Why does ApiDocsIntegrationTest start no server or container of its own?

Read this next

Primary source: the springdoc-openapi documentation — getting started, the Scalar and Swagger UI modules, and its long FAQ, which answers most "how do I document X" questions (paging, errors, interfaces, security, grouping). For what a spec can say, the OpenAPI Specification 3.1 itself, and the Swagger library's annotations reference for every attribute of @Operation, @ApiResponse, @Parameter and @Schema. Scalar's own documentation covers its scalar.* settings: theme, layout, which client languages it shows.

Glossary: the terms this lesson introduces are in the Glossary, under Lesson 14 — your quick-reference for every term we use.

Architecture decisions: the 7 choices this lesson makes, each with its reason, are in Architecture Decisions, under Lesson 14.

Code: the project at the end of this lesson · what changed in this lesson, exercises included.

💬 Discuss