chore(api-spec): update session endpoint specs #110
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| format: date-time | ||
| audience: | ||
| description: "The intended audience of the token." | ||
| type: string |
There was a problem hiding this comment.
This is currently an array of strings, so:
Suggested change
| type: string | |
| type: array | |
| items: | |
| type: string |
Comment on lines
+1544
to
+1546
| description: "The email address associated with the token's subject, if available." | ||
| type: string | ||
| format: email |
There was a problem hiding this comment.
This is currently an object with address, is_primary, is_verified so maybe something like (hope formatting works out):
Suggested change
| description: "The email address associated with the token's subject, if available." | |
| type: string | |
| format: email | |
| description: "Data about the email address associated with the token's subject, if available." | |
| type: object | |
| properties: | |
| address: | |
| description: "The actual email address." | |
| type: string | |
| format: email | |
| is_primary: | |
| description: "Indicates whether the email address is the primary address." | |
| type: boolean | |
| is_verified: | |
| description: "Indicates whether the email address is verified." | |
| type: boolean |
| @@ -1049,10 +1055,14 @@ components: | |||
| description: Date-time indicating the expiration of the session | |||
| type: string | |||
| format: date-time | |||
| deprecated: true | |||
There was a problem hiding this comment.
Mintlify now actually shows deprecated badges for some schema properties (not on schemas for endpoint operations though 🙄 ). This is good but I feel this is still not enough info:
Should we also mention in the description which other properties this one has been deprecated in favor of (in this case it would be claims.expiration, I guess)? Otherwise I wouldn't know what property I need to use.
| user_id: | ||
| description: The ID of the user the session is associated with | ||
| type: string | ||
| format: uuid4 | ||
| deprecated: true |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR updates the OpenAPI specification for the session endpoints to align the response definitions to the API changes made in teamhanko/hanko#2003 .
Changes Made
Endpoint Response Updates:
500responses (InternalServerError) to theGET /sessions/validateandPOST /sessions/validateendpoints for better documentation of potential server errors.400responses (BadRequest) for these endpoints.Schema Enhancements:
JWTClaims, to describe the claims extracted from JWTs.subject,issued_at,expiration,audience,issuer,email, andsession_id.ValidateSessionResponseschema:expires_atuser_idNotes
JWTClaimsschema as the deprecated fields will be removed in a future release.