Files
What you'll learn
- Explain what a security scheme is in OpenAPI (a named way to authenticate, declared once) and what a security requirement on an operation says
- Declare the built-in schemes with addBearerAuth, addBasicAuth, addCookieAuth and addOAuth2, and any other with addSecurity
- Mark an operation with @ApiBearerAuth() or @ApiSecurity(name), so the Swagger UI's Authorize button sends the credential and generated clients know to
- Document the sign-in exchange itself: the credentials as a DTO with examples, the token as a response model, 401 for the wrong password
Press Run tests to start the app. Its log appears here.Graded endpoints
addBearerAuth declares the built-in bearer scheme (an http scheme carrying a JWT); addSecurity declares the shelter-key scheme by hand, an API key read from a header
@ApiBearerAuth puts a bearer requirement on the create, the delete and the profile; @ApiSecurity('shelter-key') on the stats; the global 401 is on every operation
The credentials DTO has examples a reader can try, the 200 references the token model, and the 401 says what went wrong
What lesson 3 documented is still there: summaries, the Cat model on the list and the fetch, the create's 201, the delete's 204 and 404
No security requirement in the document, and no token needed: @Public() lets the guard through
The bearer requirement the document declares is enforced by the guard: 401 before the handler runs
The stats route is public to the JWT guard but ApiKeyGuard wants the header; the message says which
The x-shelter-key header the shelter-key scheme describes
The exchange the document describes: credentials in, a JWT out (its first segment is the same base64url header for every HS256 token). The token is kept for the requests below
The 401 the login documents
Authorization: Bearer <token>, exactly as the bearer scheme says
The guard put the token's payload on the request
A staff token is not a partner key: the operation's requirement is shelter-key, and only that header satisfies it
A public read, as the document's missing security requirement says
The delete's bearer requirement, enforced by the guard
204 with no body, as documented
The cat is no longer there