NestJS API Tutorial 13: Documenting it with OpenAPI

Build a real ticket-booking API with NestJS, step 13 of 15: @nestjs/swagger: Swagger UI at /docs, /openapi.json, documented errors, one document per version.

In this chapter

Documenting it with OpenAPI

Keep learning

Overview

Design behind this step The design behind this step

The idea

JSON Pointer (RFC 6901) to the bad field Each seat looks like A1 or B12 Seat A1 is already booked Only on 422: every invalid field NSCI Dome New Year Gala city is lowercase letters, like mumbai starts_at must be an ISO 8601 date-time, like 2027-01-10T19:00:00+05:30 venue_id looks like ven_1 Search events, one page at a time A query parameter is invalid \n new DocumentBuilder()\n .setTitle('Tickets API')\n .setDescription('Search events, book seats, pay. Errors are application/problem+json (RFC 9457).')\n .setVersion(version)\n .addBearerAuth()

More courses

Jobs, linked to lessons — Browse jobs where every requirement links to the chapter that teaches it. See how ready you are, how long the gap takes to close, and which listings look stale.
Match a job post to courses — Paste a job post. Each skill is matched to a track here and put in learning order, foundations first.
React from open source with patterns — Patterns extracted from Material UI, Radix, React Aria, React Hook Form, Redux Toolkit, TanStack, and Next.js — not slides about hooks.
Database in depth — How a query becomes work. Indexes, isolation, locks, and the plans that explain why a page is slow — not an ORM tour.
System Design — Core concepts first (SQL vs NoSQL, CAP, indexing, replication, sharding), then designs grouped by what carries them: the database, Redis, Kafka, or many services.
Microservices — Microservice patterns one diagram at a time: how to split a monolith, how services talk, and how data stays consistent without distributed transactions.
Kafka — A beginner-to-senior path through event logs, reliable delivery, production operations, and disaster recovery.
AI engineering for software engineers — Eight free reads, in order, for software engineers moving into AI: when to build an agent, how to build one, how to test it, and how the model works underneath.
Frontend system design — How a UI is sliced when it is a product, not a page: ownership of state, cache, routes, and what happens when the network lies.
TypeScript in depth — The type system as a design tool. Inference, narrowing, generics, and the errors that mean the model is wrong — not a catalog of utility types.
CSS in depth — See the box, then the page. Visual chapters from the box model through Flexbox surprises, Grid, selectors, and units, then backgrounds, shapes, and visual effects, each with a playground.
Accessibility — Foundations first (WCAG in plain words, semantic HTML, lists, alt text), then hands-on HTML labs, a full pass of WAI-ARIA 1.3, and a final fix-the-page challenge.
Docker — What an image is, why layers cache, and how containers find each other on a network.
Redis — Fifteen Redis patterns, one picture each: cache, session, lock, counter, rate limiter, queue, and when Redis is the wrong tool.
Kubernetes — Kubernetes from zero to operators: why it exists, Pods, Deployments and Services, then configuration, networking, storage, scheduling, scaling and security.