Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(api-spec): update session endpoint specs #110

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(api-spec): update session endpoint specs #110

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions openapi-public.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -591,6 +591,10 @@ paths:
responses:
200:
$ref: "#/components/responses/ValidateSessionResponse"
400:
$ref: "#/components/responses/BadRequest"
500:
$ref: '#/components/responses/InternalServerError'
post:
tags:
- Session Management
Expand All @@ -612,6 +616,8 @@ paths:
$ref: "#/components/responses/ValidateSessionResponse"
400:
$ref: "#/components/responses/BadRequest"
500:
$ref: '#/components/responses/InternalServerError'
/thirdparty/auth:
get:
summary: 'Initialize third party login'
Expand Down Expand Up @@ -1049,10 +1055,14 @@ components:
description: Date-time indicating the expiration of the session
type: string
format: date-time
deprecated: true
Copy link
Member

@lfleischmann lfleischmann Jan 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment above.

claims:
$ref: '#/components/schemas/JWTClaims'
required:
- isValid
BadRequest:
Expand Down Expand Up @@ -1508,6 +1518,40 @@ components:
description: "The ID of the newly created email address"
allOf:
- $ref: '#/components/schemas/UUID4'
JWTClaims:
type: object
description: "The claims extracted from a JWT."
properties:
subject:
description: "The unique identifier of the token's subject."
allOf:
- $ref: '#/components/schemas/UUID4'
issued_at:
description: "The timestamp indicating when the token was issued."
type: string
format: date-time
expiration:
description: "The timestamp indicating when the token will expire."
type: string
format: date-time
audience:
description: "The intended audience of the token."
type: string
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is currently an array of strings, so:

Suggested change
type: string
type: array
items:
type: string

issuer:
description: "The entity that issued the token."
type: string
email:
description: "The email address associated with the token's subject, if available."
type: string
format: email
Comment on lines +1544 to +1546
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

session_id:
description: "The unique identifier for the session associated with this token."
allOf:
- $ref: '#/components/schemas/UUID4'
required:
- subject
- expiration
- session_id
User:
type: object
properties:
Expand Down