Files
What you'll learn
- Explain what an OpenAPI document is, who reads it (people through the Swagger UI, tools through the JSON) and where the Swagger module gets it from
- Describe an API with DocumentBuilder and mount the document with SwaggerModule.setup, built lazily through a factory
- Make a DTO's properties appear in its schema with @ApiProperty() and @ApiPropertyOptional(), and read what the document says about them
- Tune the document with SwaggerDocumentOptions, naming operations with an operationIdFactory
Press Run tests to start the app. Its log appears here.Graded endpoints
SwaggerModule.setup at 'api' serves the generated document at /api-json; its info section is what the DocumentBuilder was told
The scanner found all four routes; with the operationIdFactory each operation is named after its method, and the POST body references the DTO's schema
@ApiProperty() makes name and age visible with their types and marks them required; @ApiPropertyOptional() adds breed without requiring it
The same setup serves the UI's HTML page at /api; it loads the document from its init script (open it in a new tab to see it rendered)
The UI does not fetch /api-json; the document is embedded in the script the page loads
Documenting changes nothing about the routes: a cat is created as before
A negative age is refused by the ValidationPipe, not by anything OpenAPI does; the document describes, the pipe enforces
The entity as stored, read by id; the document's GET /cats/{id} is this route
DELETE answers 204 with no body, which the document will describe in a later lesson
The cat is no longer there