Add presence swagger and template.
parent
ec631c60d4
commit
334e10468d
@ -0,0 +1,207 @@
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server v1 Presence API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/api/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
accessToken:
|
||||
type: apiKey
|
||||
description: The user_id or application service access_token
|
||||
name: access_token
|
||||
in: query
|
||||
paths:
|
||||
"/presence/{userId}/status":
|
||||
put:
|
||||
summary: Update this user's presence state.
|
||||
description: |-
|
||||
This API sets the given user's presence state. You cannot set the presence
|
||||
state of another user.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
description: The user whose presence state to update.
|
||||
required: true
|
||||
x-example: "@alice:example.com"
|
||||
- in: body
|
||||
name: presenceState
|
||||
description: The updated presence state.
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
example: |-
|
||||
{
|
||||
"presence": "online",
|
||||
"status_msg": "I am here."
|
||||
}
|
||||
properties:
|
||||
presence:
|
||||
type: string
|
||||
enum: ["online", "offline", "unavailable", "free_for_chat"]
|
||||
description: The new presence state.
|
||||
status_msg:
|
||||
type: string
|
||||
description: "The status message to attach to this state."
|
||||
required: ["presence"]
|
||||
responses:
|
||||
200:
|
||||
description: The new presence state was set.
|
||||
examples:
|
||||
application/json: |-
|
||||
{}
|
||||
schema:
|
||||
type: object # empty json object
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/error.yaml"
|
||||
get:
|
||||
summary: Get this user's presence state.
|
||||
description: |-
|
||||
Get the given user's presence state.
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
description: The user whose presence state to get.
|
||||
required: true
|
||||
x-example: "@alice:example.com"
|
||||
responses:
|
||||
200:
|
||||
description: The presence state for this user.
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"presence": "unavailable",
|
||||
"last_active_ago": 420845,
|
||||
"status_msg": null
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
presence:
|
||||
type: string
|
||||
enum: ["online", "offline", "unavailable", "free_for_chat"]
|
||||
description: This user's presence.
|
||||
last_active_ago:
|
||||
type: integer
|
||||
description: |-
|
||||
The length of time in milliseconds since an action was performed
|
||||
by this user.
|
||||
status_msg:
|
||||
type: string
|
||||
description: The state message for this user if one was set.
|
||||
404:
|
||||
description: |-
|
||||
There is no presence state for this user. This user may not exist or
|
||||
isn't exposing presence information to you.
|
||||
"/presence/list/{userId}":
|
||||
post:
|
||||
summary: Add or remove users from this presence list.
|
||||
description: |-
|
||||
Adds or removes users from this presence list.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
description: The user whose presence list is being modified.
|
||||
required: true
|
||||
x-example: "@alice:example.com"
|
||||
- in: body
|
||||
name: presence_diff
|
||||
description: The modifications to make to this presence list.
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
example: |-
|
||||
{
|
||||
"invite": [
|
||||
"@bob:matrix.org"
|
||||
],
|
||||
"drop": [
|
||||
"@alice:matrix.org"
|
||||
]
|
||||
}
|
||||
properties:
|
||||
invite:
|
||||
type: array
|
||||
description: A list of user IDs to add to the list.
|
||||
items:
|
||||
type: string
|
||||
description: A list of user IDs.
|
||||
drop:
|
||||
type: array
|
||||
description: A list of user IDs to remove from the list.
|
||||
items:
|
||||
type: string
|
||||
description: A list of user IDs.
|
||||
responses:
|
||||
200:
|
||||
description: The list was updated.
|
||||
examples:
|
||||
application/json: |-
|
||||
{}
|
||||
schema:
|
||||
type: object # empty json object
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/error.yaml"
|
||||
get:
|
||||
summary: Get presence events for this presence list.
|
||||
description: |-
|
||||
Retrieve a list of presence events for every user on this list.
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
description: The user whose presence list should be retrieved.
|
||||
required: true
|
||||
x-example: "@alice:example.com"
|
||||
responses:
|
||||
200:
|
||||
description: A list of presence events for this list.
|
||||
examples:
|
||||
application/json: |-
|
||||
[
|
||||
{
|
||||
"content": {
|
||||
"avatar_url": "mxc://matrix.org/AfwefuigfWEfhuiPP",
|
||||
"displayname": "Alice Margatroid",
|
||||
"last_active_ago": 395,
|
||||
"presence": "offline",
|
||||
"user_id": "@alice:matrix.org"
|
||||
}
|
||||
"type": "m.presence"
|
||||
},
|
||||
{
|
||||
"content": {
|
||||
"avatar_url": "mxc://matrix.org/FWEhuiwegfWEfhuiwf",
|
||||
"displayname": "Marisa Kirisame",
|
||||
"last_active_ago": 16874,
|
||||
"presence": "online",
|
||||
"user_id": "@marisa:matrix.org"
|
||||
}
|
||||
"type": "m.presence"
|
||||
}
|
||||
]
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
title: PresenceEvent
|
||||
allOf:
|
||||
- "$ref": "definitions/event.yaml"
|
||||
|
Loading…
Reference in New Issue