Files
What you'll learn
- Group operations with @ApiTags and describe the tag in the DocumentBuilder; add a summary with @ApiOperation and a shared header with @ApiHeader
- Document responses with @ApiResponse and its status shorthands, with a model class as the type, and declare one response for every operation with addGlobalResponse
- Describe a response the scanner cannot see, a generic page of results, with @ApiExtraModels, getSchemaPath and allOf, packaged as a reusable decorator with applyDecorators
- Document a file upload as a multipart/form-data body with @ApiConsumes and a binary-string property
Press Run tests to start the app. Its log appears here.Graded endpoints
addTag's second argument describes the tag; @ApiTags on the controller puts every operation under it, where the default tag would have been the controller's name
@ApiOperation gives three operations a summary; @ApiHeader on the class adds the X-Shelter-Site header parameter to every operation, before the ones the scanner found
With @ApiProperty on its columns the entity is a schema; the responses of POST /cats and GET /cats/:id reference it, with the shorthand decorators' status and description
@ApiNoContentResponse and @ApiNotFoundResponse document the delete; addGlobalResponse puts the 500 on all five operations without repeating it
The decorator registers PaginatedDto and Cat as extra models and composes the 200 response: PaginatedDto's properties plus results as an array of Cat
@ApiConsumes names the content type and @ApiBody the DTO; its photo property is a string in binary format, which the Swagger UI renders as a file picker
The response is the Cat the document promised, with the columns the entity added
A second row, so the page below has something to skip
The shape the allOf described: total, limit, offset, and results holding Cats
A multipart request with a photo field, as the document describes it; the file name is stored on the cat
@ApiNotFoundResponse described it; NotFoundException produces it
204 with no body, as documented
The page after the delete: total went down with it