OpenAPI
On this page 8 topics
Overview
Topics
- Swagger UI
- OpenAPI specification
- examples
- API documentation
Learn first
2 h of practice (estimate)
Learning outcomes
- Read an OpenAPI document: paths, operations, schemas, responses.
- Generate an OpenAPI document from Spring code and serve Swagger UI.
- Enrich it with descriptions, examples, and error responses.
- Explain code-first vs contract-first and the trade-offs.
Lessons
Lab and exercises
Lab
JNR-021-LAB1 · Documented Shop API
Outcomes: 1–4 · Time: ~2 h Add springdoc to Shop API and serve Swagger UI. Add descriptions and examples to every operation and DTO, and document the Problem Details error responses. Commit the generated spec file to the repository.
Acceptance: a new developer can call every endpoint using only Swagger UI.
Exercises (assessment: documentation review)
| ID | Outcome | Task |
|---|---|---|
| JNR-021-EX01 | 1 | Given a small OpenAPI YAML, list its paths, operations, schemas, and the response codes of one operation. |
| JNR-021-EX02 | 2 | Add springdoc to Shop API and open Swagger UI; find the raw JSON spec URL. |
| JNR-021-EX03 | 3 | Add summary, field descriptions, and a request example to POST /products. |
| JNR-021-EX04 | 3 | Document 400 and 404 responses on GET /products/{id} and POST /products. |
| JNR-021-EX05 | 4 | Compare code-first and contract-first for a partner-facing API and choose one with reasons. |
| JNR-021-EX06 | 1, 3 | Review a deliberately poor spec: find five problems (missing errors, no examples, wrong status, ...). |
Show solutions
- EX01 Check that you listed the
pathskeys, each HTTP method under them,components/schemasnames, and eachresponseskey. - EX02 Usually
/swagger-ui.htmland/v3/api-docs(verify for the springdoc version used). - EX03
@Operation(summary = "..."),@Schema(description = "...", example = "Pen")on the record components. - EX04
@ApiResponse(responseCode = "404", ...)per operation, referencing the Problem Details schema. - EX05 Contract-first suits partner APIs: the design is reviewed and agreed before code; mention the sync risk and a check in CI.
- EX06 Typical problems: missing error responses, no examples, wrong create status, missing descriptions, undocumented parameters.
Outcome 4 is also checked by quiz Q09 and Q10; the lab criterion covers outcome 2 end to end.
Quiz
Outcomes: O1 read a spec · O2 generate and serve docs · O3 enrich docs · O4 code-first vs contract-first.
A self-check for you: nothing is graded, saved or sent anywhere. Choose an answer, then check it. You can try again as often as you like.
Practical part
Six exercises JNR-021-EX01 to EX06 plus the documented-API lab. Pass: at least five exercises and a lab where every endpoint is callable from Swagger UI alone, with the spec committed.
Common mistakes
Undocumented error responses; docs drifting from behavior.
Assessment
Documentation review.
Career relevance
Contract testing (MID-045) and API management (ARC-025).