OpenAPI

Describe the cats API so that people and tools can read it: generate an OpenAPI document from the code you already have, shape every schema, parameter and response with the @nestjs/swagger decorators, declare how callers authenticate, reuse DTOs through mapped types, and serve more than one specification from the same app.

lessons: 5
level: intermediate
time: 2.5 hours

Start with Introduction

Describing the API

A document generated from the routes, then made accurate: what each schema, parameter and response really looks like.

1
Introduction
Generate an OpenAPI document for the shelter's cats API from the code it already has: describe it with a DocumentBuilder, mount the Swagger UI at /api, make the DTO's properties visible to the document, and name each operation after its handler.
Read the theory
2
Types and parameters
Make the document say what the API really accepts: examples, bounds and defaults on each property, an enum with a schema of its own, an optional query parameter with allowed values, a described path parameter, and a request body that is an array of DTOs.
Read the theory
3
Operations
Describe each operation the way its callers experience it: a tag with a description, a summary, the header every route accepts, every response with its status and model, a global 500, a paginated response built with getSchemaPath, and a multipart upload body.
Read the theory

Shaping the document

How callers authenticate, DTOs derived from one another, and what to leave out or split off.

4
Security schemes
Tell callers how to authenticate: declare the staff's bearer JWT and the partners' API key as security schemes, mark each operation with the scheme it needs, document the sign-in exchange, and declare the 401 every operation can answer.
Read the theory
5
Mapped types and other features
Derive the update, birthday and intake DTOs from CreateCatDto with the mapped types from @nestjs/swagger, so the document and the validation follow one definition; keep an internal column and a staff-only route out of the document; and serve the shelter's internal routes as a second specification of their own.
Read the theory