CicloUrbana now has a complete API: thirteen endpoints, validation at the edge, DTOs that separate the domain from the contract and uniform errors in Problem Details format. And yet, everything we know about it —which fields each endpoint accepts, what it returns, which errors it can produce— lives in the code and in our heads. If tomorrow the Ribalta mobile app team or the council's open data portal team wanted to integrate, they would have to read our code or ask us endpoint by endpoint. In this lesson we turn that tacit knowledge into a formal contract, generated automatically from the code itself, readable by humans in a web interface and by machines to generate clients. With it module 3 closes and Ribalta's API is ready for others to use.

1. What OpenAPI is and why a machine-readable contract
2. Code-first versus design-first
3. Integrating springdoc-openapi
4. Global metadata: the OpenAPI bean
5. Documenting operations: @Tag and @Operation
6. Parameters and responses: @Parameter and @ApiResponse
7. Documenting the DTOs with @Schema
8. Bean Validation in the schema, automatically
9. Documenting the Problem Details errors
10. Grouping endpoints with GroupedOpenApi
11. Swagger UI: testing the API from the browser
12. Exporting the contract and generating a client
13. Not exposing Swagger UI in production
14. Common Mistakes and Tips
15. Exercises

OpenAPI is a specification for describing HTTP APIs in a structured document, in JSON or YAML. The current version is OpenAPI 3.1, which unlike 3.0 is fully compatible with JSON Schema, allowing data structures to be described precisely. A fragment of CicloUrbana's document:

Being machine-readable is what changes the way you work:

The contrast with the alternative —a text document or a wiki page— is that such documentation goes out of sync on day one: nobody remembers to update it when adding a field, and three months later it lies. A contract generated from the code cannot lie.

There are two ways of arriving at the OpenAPI document:

The course uses code-first with springdoc for two reasons: a pedagogical one, that you can see the direct relationship between each annotation and the resulting document, and a practical one, that for a small team with a single backend maintaining a thousand-line openapi.yaml by hand costs more than it gives.

That said, it is worth understanding why design-first dominates in large organisations: when five teams consume your API, the contract is a prior negotiation and not a by-product. Writing it first lets the mobile team start against a mock the same day the backend starts implementing it, and it avoids the most cited risk of code-first: that the API ends up being a reflection of the internal model instead of a design made for whoever consumes it. It is worth noting that in this module we have in fact worked design-first without tools: the table of thirteen endpoints from 03-01 was written before any controller, only it lived in a Markdown table and now it becomes a formal artefact.

springdoc-openapi inspects the @RestControllers, their annotations and their types at runtime, and builds the OpenAPI document. A single dependency:

The suffix matters: -ui includes Swagger UI, whereas springdoc-openapi-starter-webmvc-api generates only the document; for a reactive application it would be webflux. We start up and there are already two new endpoints, without writing a line:

The thirteen endpoints are there, with their parameters and their response schemas deduced from the DTOs, and at http://localhost:8080/swagger-ui.html there is a browsable interface. All the work of the previous lessons —precise types, specific DTOs, declarative validation— is what makes that automatic deduction good: a controller returning Map<String, Object> would produce nothing useful.

The configuration in YAML:

doc-expansion: none deserves a comment: with thirteen endpoints expanded the landing page is a wall of text, and collapsed you see the API's structure at a glance.

Annotations document endpoints; global metadata —title, version, contact, licence and servers— is declared in a bean:

Three useful details. The list of Servers appears in Swagger UI as a dropdown, so whoever tries the API chooses which environment to fire requests at without editing URLs. The version is injected with @Value rather than hard-coded, so the documentation always states which version is deployed (in module 7 it will be able to come from the pom.xml via Actuator). And the description accepts Markdown: it is the place for cross-cutting conventions, such as the error format, pagination or authentication.

Tags group the endpoints into sections inside Swagger UI and are declared at class level: @Tag(name = "Stations", description = "Querying and managing Ribalta's docking stations") on StationController.

And @Operation describes each method:

operationId is the most neglected attribute and the one with the greatest consequences: it is the name the method will have in the generated clients. Without it, springdoc invents something like getById_1, and that ugly name ends up in every client team's code. With operationId = "getStationById", the Android team's Kotlin client will have a readable getStationById(id).

@Parameter documents each input:

The examples are not decorative: Swagger UI preloads them into the "Try it out" form, so whoever tries the API for the first time gets a call that works without inventing values. And @ApiResponse describes each possible response:

With @ExampleObject you document concrete bodies, which is especially valuable when the same status code has several causes:

Swagger UI shows a dropdown with the two examples: it is the most effective way of explaining the project's error codes without writing a separate document.

The DTOs from 03-05 become OpenAPI schemas, and @Schema enriches them:

accessMode = READ_ONLY is the most useful and least known: it marks a field as server-generated, and client generators exclude it from request objects, so the client cannot try to send availableBikes. It is the contract-level translation of the separation between request and response DTOs.

In the request DTOs, requiredMode and the examples are what matter:

Enums document themselves with their list of values, but it is worth describing each state of the Ribalta domain:

Here comes the reward for lesson 03-04. springdoc reads the Bean Validation annotations and translates them into OpenAPI schema constraints, with no effort at all.

The schema generated for CreateStationRequest:

None of those constraints was written for the documentation: they all came from the validation annotations. A single source of truth that validates at runtime and documents at the same time, with no chance of the two drifting apart.

The custom constraints we built —@BikePlate, @MultipleOf— are unknown to springdoc, so they have to be documented by hand with @Schema(pattern = "^RB-\\d{4}$", example = "RB-0142"). That is a good argument for composing your own constraints on top of the standard ones: if @BikePlate had been defined as a composed annotation including @Pattern, springdoc would have deduced the pattern on its own.

Repeating three error @ApiResponses on each of the thirteen endpoints is exactly the kind of repetition that ends up out of sync. The solution is your own composed annotations:

Since ProblemDetail is a Spring class, its generated schema does not include our extensions (code, trace, errors), so the right move is to declare a schema of our own that documents them:

The code field documented with "use it in your logic instead of the text" is exactly the kind of guidance that stops a client from comparing strings and breaking when we translate a message.

As the API grows, a single document with everything mixed together becomes hard to navigate. GroupedOpenApi produces several documents from the same application:

Each group has its own document at /v3/api-docs/public, /v3/api-docs/rentals and /v3/api-docs/internal, and Swagger UI shows a dropdown for switching between them. The three usual uses: separating audiences, publishing only the public group on the council's portal; separating versions, with a /api/v1/** group and an /api/v2/** one; and generating different clients, one per group, so that the citizen app does not drag along the operator panel's operations.

At http://localhost:8080/swagger-ui.html the complete API appears, grouped by the tags from section 5, and each operation expands to show its description, its parameters with examples, the body schema and every possible response. The "Try it out" button turns the documentation into an HTTP client: it fills the form with the examples we declared, lets you edit them and fires the real request against the server chosen in the dropdown, showing the response, its headers, the status code and —very handy for sharing— the equivalent curl command.

It is worth understanding what makes it genuinely useful, because it is not the tool itself: it is that the examples are properly set. An endpoint documented without an example forces you to invent values, and trying POST /api/v1/stations without knowing the capacity must be a multiple of 6 ends in a 400. With the examples, any new developer's first call works. A detail for module 5: when we add JWT, Swagger UI will show an "Authorize" button if we declare the security scheme, and from then on it will include the token in every call.

The document can be dumped to a file during the build with the springdoc plugin, which starts the application, downloads the JSON and stops it:

It requires the spring-boot-maven-plugin with the start and stop goals bound to pre-integration-test and post-integration-test. The result, target/openapi.json, is the artefact that gets published: it is uploaded to the council's portal, compared with the previous version to detect incompatible changes (module 8) and it feeds client generation with the openapi-generator-maven-plugin:

The generator supports more than fifty languages: java, kotlin, typescript-axios, python, swift5, go. Ribalta's Android app team generates its Kotlin client from the same openapi.json, and the web portal team its TypeScript one.

The generated code looks like this:

Here you can see why we insisted on operationId: those method names come straight from it. And the StationDetailResponse and CreateStationRequest types are generated from our schemas, with the same validation constraints, so that the client validates before sending because the contract carries them inside. An additional benefit that shows up over time: if we remove a field from a DTO, the generated client stops compiling on the next update; an incompatible change that in an API without a contract is discovered in production is discovered here at compile time.

Swagger UI is a development tool. In production it is a detailed map of your attack surface: every endpoint, every parameter, every expected format, and a form for trying them out.

The simplest way of switching it off is springdoc.api-docs.enabled: false and springdoc.swagger-ui.enabled: false.

And the correct approach, with profiles: leave it active in the base application.yml —used by development and the tests— and disable it in application-prod.yml, which overrides it when starting with --spring.profiles.active=prod. Profiles are covered in 07-02, where we will pick this configuration up again.

If Ribalta city council wants to publish the documentation of its open API, the right route is to export the openapi.json during the build (section 12) and serve it from a separate static portal, which exposes neither the real application nor the ability to fire requests at it. And one last risk: springdoc generates the documentation by inspecting every controller in the context, so a forgotten internal controller ends up published; springdoc.paths-to-match: /api/** is a cheap defence against that oversight.

Documenting only the happy path. An endpoint with only the 200 documented forces the client to discover the errors in production. The error @ApiResponses are half the value of the contract.

Forgetting operationId. The generated clients' methods come out with automatic, ugly names, and they change on their own when the code is reordered.

Leaving Swagger UI reachable in production. It is a complete description of your attack surface.

Putting in examples that do not work. An example with capacity 25 when the constraint demands multiples of 6 makes everybody's first attempt fail. Copy the examples from real requests.

Documenting the entity instead of the DTO. If @Schema is placed on Station and the endpoint returns StationResponse, the documentation describes something the API does not return.

Repeating the same @ApiResponses in every method. Thirteen copies that drift apart: use composed annotations. And do not expect springdoc to guess your own constraints: @BikePlate does not appear in the schema, so add the pattern by hand or compose your constraint on top of @Pattern.

Tip: read the /v3/api-docs as if you were an external client. If a field cannot be understood without opening the code, a description is missing; it is the most effective review there is and it takes ten minutes. And version the openapi.json in the repository: comparing the generated one with the previous one on every build turns any incompatible change into a continuous integration failure, before it reaches the clients.

RentalController has no OpenAPI annotations at all. Document the three operations —start, finish and query— with their tags, summaries, operationIds, parameters, examples and every possible error response, including the business ones from 03-06.

The operations that write (POST, PUT, PATCH, DELETE) share a different set of errors from the read ones: besides 400 and 500, they can give 409 and 422. Create @WriteErrorResponses and apply it, avoiding duplication of the common error definitions.

Configure the build to export openapi.json and add a check that fails when a change breaks the contract. Explain which changes it must detect and which it must allow.

Solution 1.

Two practical warnings. The first, a name clash: @RequestBody exists both in OpenAPI (io.swagger.v3.oas.annotations.parameters) and in Spring, so if you need the OpenAPI one you will have to fully qualify one of the two; the cleanest thing is to put the examples in the DTO's @Schema, as the code above does. The second, and it is the point of the exercise: the documentation explains the semantics, not just the types —that finishing is not idempotent, that the amount is not known until the end, that the minimum charge depends on configuration. None of that can be deduced from the Java signatures, and it is exactly what a client team needs to know.

Solution 2.

We take advantage of the fact that composed annotations can be nested:

Composition is what makes this solution maintainable: the day the error format changes —by adding a support field to the schema, say—, you touch CommonErrorResponses and the change reaches the thirteen endpoints; had we copied the @ApiResponses, there would be thirteen places to update and one would be left behind. A practical warning: springdoc reads nested annotations, but it is worth verifying it after creating them, and the check is straightforward:

Solution 3.

The export is the one from section 12, additionally binding the application's start and stop to the integration cycle with the spring-boot-maven-plugin (start on pre-integration-test, stop on post-integration-test). Then, the compatibility check with openapi-diff against the published contract:

--fail-on-incompatible returns a non-zero exit code if it detects a change that breaks clients, which makes continuous integration fail (module 8).

This table is, point for point, the compatible and incompatible changes table from lesson 03-01. The difference is that there it was a guideline you had to remember and here it is an automatic check that runs on every build. That is the real jump in value of having a formal contract: it turns a rule of discipline into a technical barrier.

The complete process when publishing: target/openapi.json is generated, compared with the published one and, if the change is compatible, copied over openapi-published.json and uploaded to the council's portal. If it is incompatible, continuous integration fails and the team consciously decides whether an /api/v2 needs negotiating.

Module 3 closes with the CicloUrbana API described in a formal contract that generates itself. You know what OpenAPI 3.1 is and what a machine-readable contract unlocks: generated clients, documentation that does not drift, contract tests, mock servers and developer portals. You have compared code-first and design-first with the judgement to choose according to team size. You integrated springdoc-openapi with a single dependency and saw the thirteen endpoints appear documented without writing anything, because the work had been done beforehand: precise types, specific DTOs and declarative validation. You configured the global metadata with the OpenAPI bean, documented operations with @Tag and @Operation —taking care of operationId, which ends up being the method name in other teams' clients—, the parameters with @Parameter and examples that make the first call work, and the responses with @ApiResponse and @ExampleObject. You enriched the DTOs with @Schema, including accessMode = READ_ONLY for the fields the server computes, and you checked that the Bean Validation constraints from 03-04 appear in the schema on their own: a single source of truth that validates and documents at once. You documented the Problem Details from 03-06 with composed annotations that avoid thirteen copies, grouped with GroupedOpenApi, exported the openapi.json during the build and generated a Java client with the openapi-generator-maven-plugin. And you know why Swagger UI must not be left exposed in production.

Look back at the whole module. It began with a single endpoint, GET /api/v1/stations, returning a list of raw domain objects. It ends with thirteen endpoints designed around the REST constraints and Richardson level 2, with the right verbs and status codes, the Location header on creations and ETag for concurrency control. With declarative validation at the edge, constraints specific to the Ribalta domain and internationalisation in three languages. With a DTO hierarchy that cleanly separates what CicloUrbana knows from what it promises, and a mapping that allows renaming in the domain without breaking a single client. With uniform RFC 7807 errors, a global handler, stable codes and traces correlatable with the log. And with a publishable OpenAPI contract from which other teams generate their client without asking us a thing. The API Ribalta's citizens will see is complete.

It is missing, though, the most elementary thing: when the application restarts, everything disappears. The four stations are loaded again from DemoStationLoader, the bikes that were registered vanish and the day's rentals are lost. Everything lives in a ConcurrentHashMap that exists as long as the process does. We have been able to get this far thanks to having hidden that provisional nature behind the StationRepository interface since lesson 02-01, a decision that now collects its reward.

Module 4, Data Access with Spring Boot, replaces it with real persistence. We will see what JPA, Hibernate and Spring Data are and how they relate; we will configure data sources and a connection pool; we will turn Station, Bike and Rental into JPA entities with their identifiers and their optimistic version —the one that will replace the ShallowEtagHeaderFilter from 03-03—; we will model the relationships between them along with the problems we already anticipated, lazy loading and N+1; we will use Spring Data repositories and their derived query methods; we will understand transactions and why @Transactional on the service changes the rules of the game; and we will manage schema evolution with Flyway. Ribalta's four stations are about to survive a restart.