Upgrade Swagger data to OpenAPI 3.1 (#1310)
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille
GitHub
parent
c64a616d54
commit
45b6aaf07a
118 changed files with 15064 additions and 12727 deletions
|
|
@ -12,21 +12,12 @@
|
|||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
swagger: '2.0'
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: "Matrix Push Notification API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/push/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
title: Matrix Push Notification API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/notify":
|
||||
/notify:
|
||||
post:
|
||||
summary: Notify a push gateway about an event.
|
||||
description: |-
|
||||
|
|
@ -48,182 +39,203 @@ paths:
|
|||
This means that the HTTP path may be different depending on the push
|
||||
gateway.
|
||||
operationId: notify
|
||||
parameters:
|
||||
- in: body
|
||||
name: notification
|
||||
description: Information about the push notification.
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"notification": {
|
||||
"event_id": "$3957tyerfgewrf384",
|
||||
"room_id": "!slw48wfj34rtnrf:example.com",
|
||||
"type": "m.room.message",
|
||||
"sender": "@exampleuser:matrix.org",
|
||||
"sender_display_name": "Major Tom",
|
||||
"room_name": "Mission Control",
|
||||
"room_alias": "#exampleroom:matrix.org",
|
||||
"prio": "high",
|
||||
"content": {
|
||||
"msgtype": "m.text",
|
||||
"body": "I'm floating in a most peculiar way."
|
||||
},
|
||||
"counts": {
|
||||
"unread" : 2,
|
||||
"missed_calls": 1
|
||||
},
|
||||
"devices": [
|
||||
{
|
||||
"app_id": "org.matrix.matrixConsole.ios",
|
||||
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
|
||||
"pushkey_ts": 12345678,
|
||||
"data" : {},
|
||||
"tweaks": {
|
||||
"sound": "bing"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"notification": {
|
||||
"event_id": "$3957tyerfgewrf384",
|
||||
"room_id": "!slw48wfj34rtnrf:example.com",
|
||||
"type": "m.room.message",
|
||||
"sender": "@exampleuser:matrix.org",
|
||||
"sender_display_name": "Major Tom",
|
||||
"room_name": "Mission Control",
|
||||
"room_alias": "#exampleroom:matrix.org",
|
||||
"prio": "high",
|
||||
"content": {
|
||||
"msgtype": "m.text",
|
||||
"body": "I'm floating in a most peculiar way."
|
||||
},
|
||||
"counts": {
|
||||
"unread": 2,
|
||||
"missed_calls": 1
|
||||
},
|
||||
"devices": [
|
||||
{
|
||||
"app_id": "org.matrix.matrixConsole.ios",
|
||||
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
|
||||
"pushkey_ts": 12345678,
|
||||
"data": {},
|
||||
"tweaks": {
|
||||
"sound": "bing"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
required: ["notification"]
|
||||
properties:
|
||||
notification:
|
||||
type: object
|
||||
title: Notification
|
||||
description: Information about the push notification
|
||||
required: ["devices"]
|
||||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
description: |-
|
||||
The Matrix event ID of the event being notified about.
|
||||
This is required if the notification is about a
|
||||
particular Matrix event. It may be omitted for notifications
|
||||
that only contain updated badge counts. This ID can and
|
||||
should be used to detect duplicate notification requests.
|
||||
room_id:
|
||||
type: string
|
||||
description: |-
|
||||
The ID of the room in which this event occurred.
|
||||
Required if the notification relates to a specific
|
||||
Matrix event.
|
||||
type:
|
||||
type: string
|
||||
description: |-
|
||||
The type of the event as in the event's `type` field.
|
||||
sender:
|
||||
type: string
|
||||
description: |-
|
||||
The sender of the event as in the corresponding event field.
|
||||
sender_display_name:
|
||||
type: string
|
||||
description: |-
|
||||
The current display name of the sender in the room in which
|
||||
the event occurred.
|
||||
room_name:
|
||||
type: string
|
||||
description: The name of the room in which the event occurred.
|
||||
room_alias:
|
||||
type: string
|
||||
description: An alias to display for the room in which the event occurred.
|
||||
user_is_target:
|
||||
type: boolean
|
||||
description: |-
|
||||
This is true if the user receiving the notification is the
|
||||
subject of a member event (i.e. the `state_key` of the
|
||||
member event is equal to the user's Matrix ID).
|
||||
prio:
|
||||
type: string
|
||||
enum: ["high", "low"]
|
||||
description: |-
|
||||
The priority of the notification. If omitted, `high` is
|
||||
assumed. This may be used by push gateways to deliver less
|
||||
time-sensitive notifications in a way that will preserve
|
||||
battery power on mobile devices.
|
||||
content:
|
||||
type: object
|
||||
title: EventContent
|
||||
description: |-
|
||||
The `content` field from the event, if present. The pusher
|
||||
may omit this if the event had no content or for any other
|
||||
reason.
|
||||
counts:
|
||||
type: object
|
||||
title: Counts
|
||||
description: |-
|
||||
This is a dictionary of the current number of unacknowledged
|
||||
communications for the recipient user. Counts whose value is
|
||||
zero should be omitted.
|
||||
properties:
|
||||
unread:
|
||||
type: integer
|
||||
description: |-
|
||||
The number of unread messages a user has across all of the
|
||||
rooms they are a member of.
|
||||
missed_calls:
|
||||
type: integer
|
||||
description: |-
|
||||
The number of unacknowledged missed calls a user has
|
||||
across all rooms of which they are a member.
|
||||
devices:
|
||||
type: array
|
||||
title: Devices
|
||||
description: |-
|
||||
This is an array of devices that the notification should be sent to.
|
||||
items:
|
||||
required:
|
||||
- notification
|
||||
properties:
|
||||
notification:
|
||||
type: object
|
||||
title: Notification
|
||||
description: Information about the push notification
|
||||
required:
|
||||
- devices
|
||||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
description: |-
|
||||
The Matrix event ID of the event being notified about.
|
||||
This is required if the notification is about a
|
||||
particular Matrix event. It may be omitted for notifications
|
||||
that only contain updated badge counts. This ID can and
|
||||
should be used to detect duplicate notification requests.
|
||||
room_id:
|
||||
type: string
|
||||
description: |-
|
||||
The ID of the room in which this event occurred.
|
||||
Required if the notification relates to a specific
|
||||
Matrix event.
|
||||
type:
|
||||
type: string
|
||||
description: The type of the event as in the event's `type` field.
|
||||
sender:
|
||||
type: string
|
||||
description: The sender of the event as in the corresponding event field.
|
||||
sender_display_name:
|
||||
type: string
|
||||
description: |-
|
||||
The current display name of the sender in the room in which
|
||||
the event occurred.
|
||||
room_name:
|
||||
type: string
|
||||
description: The name of the room in which the event occurred.
|
||||
room_alias:
|
||||
type: string
|
||||
description: An alias to display for the room in which the event occurred.
|
||||
user_is_target:
|
||||
type: boolean
|
||||
description: |-
|
||||
This is true if the user receiving the notification is the
|
||||
subject of a member event (i.e. the `state_key` of the
|
||||
member event is equal to the user's Matrix ID).
|
||||
prio:
|
||||
type: string
|
||||
enum:
|
||||
- high
|
||||
- low
|
||||
description: |-
|
||||
The priority of the notification. If omitted, `high` is
|
||||
assumed. This may be used by push gateways to deliver less
|
||||
time-sensitive notifications in a way that will preserve
|
||||
battery power on mobile devices.
|
||||
content:
|
||||
type: object
|
||||
title: Device
|
||||
title: EventContent
|
||||
description: |-
|
||||
The `content` field from the event, if present. The pusher
|
||||
may omit this if the event had no content or for any other
|
||||
reason.
|
||||
counts:
|
||||
type: object
|
||||
title: Counts
|
||||
description: |-
|
||||
This is a dictionary of the current number of unacknowledged
|
||||
communications for the recipient user. Counts whose value is
|
||||
zero should be omitted.
|
||||
properties:
|
||||
app_id:
|
||||
type: string
|
||||
description: |-
|
||||
The `app_id` given when the pusher was created.
|
||||
pushkey:
|
||||
type: string
|
||||
description: The `pushkey` given when the pusher was created.
|
||||
pushkey_ts:
|
||||
unread:
|
||||
type: integer
|
||||
format: int64
|
||||
description: |-
|
||||
The unix timestamp (in seconds) when the
|
||||
pushkey was last updated.
|
||||
data:
|
||||
type: object
|
||||
title: PusherData
|
||||
The number of unread messages a user has across all of the
|
||||
rooms they are a member of.
|
||||
missed_calls:
|
||||
type: integer
|
||||
description: |-
|
||||
A dictionary of additional pusher-specific data. For
|
||||
'http' pushers, this is the data dictionary passed in at
|
||||
pusher creation minus the `url` key.
|
||||
tweaks:
|
||||
type: object
|
||||
title: Tweaks
|
||||
description: |-
|
||||
A dictionary of customisations made to the way this
|
||||
notification is to be presented. These are added by push rules.
|
||||
required: ['app_id', 'pushkey']
|
||||
The number of unacknowledged missed calls a user has
|
||||
across all rooms of which they are a member.
|
||||
devices:
|
||||
type: array
|
||||
title: Devices
|
||||
description: This is an array of devices that the notification should be sent
|
||||
to.
|
||||
items:
|
||||
type: object
|
||||
title: Device
|
||||
properties:
|
||||
app_id:
|
||||
type: string
|
||||
description: The `app_id` given when the pusher was created.
|
||||
pushkey:
|
||||
type: string
|
||||
description: The `pushkey` given when the pusher was created.
|
||||
pushkey_ts:
|
||||
type: integer
|
||||
format: int64
|
||||
description: |-
|
||||
The unix timestamp (in seconds) when the
|
||||
pushkey was last updated.
|
||||
data:
|
||||
type: object
|
||||
title: PusherData
|
||||
description: |-
|
||||
A dictionary of additional pusher-specific data. For
|
||||
'http' pushers, this is the data dictionary passed in at
|
||||
pusher creation minus the `url` key.
|
||||
tweaks:
|
||||
type: object
|
||||
title: Tweaks
|
||||
description: |-
|
||||
A dictionary of customisations made to the way this
|
||||
notification is to be presented. These are added by push rules.
|
||||
required:
|
||||
- app_id
|
||||
- pushkey
|
||||
description: Information about the push notification.
|
||||
required: true
|
||||
responses:
|
||||
200:
|
||||
"200":
|
||||
description: A list of rejected push keys.
|
||||
examples:
|
||||
application/json: {
|
||||
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
|
||||
}
|
||||
schema:
|
||||
type: object # empty json object
|
||||
properties:
|
||||
rejected:
|
||||
type: array
|
||||
description: |-
|
||||
A list of all pushkeys given in the notification request that
|
||||
are not valid. These could have been rejected by an upstream
|
||||
gateway because they have expired or have never been valid.
|
||||
Homeservers must cease sending notification requests for these
|
||||
pushkeys and remove the associated pushers. It may not
|
||||
necessarily be the notification in the request that failed:
|
||||
it could be that a previous notification to the same pushkey
|
||||
failed. May be empty.
|
||||
items:
|
||||
type: string
|
||||
description: A pushkey that has been rejected.
|
||||
required: ['rejected']
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object # empty json object
|
||||
properties:
|
||||
rejected:
|
||||
type: array
|
||||
description: |-
|
||||
A list of all pushkeys given in the notification request that
|
||||
are not valid. These could have been rejected by an upstream
|
||||
gateway because they have expired or have never been valid.
|
||||
Homeservers must cease sending notification requests for these
|
||||
pushkeys and remove the associated pushers. It may not
|
||||
necessarily be the notification in the request that failed:
|
||||
it could be that a previous notification to the same pushkey
|
||||
failed. May be empty.
|
||||
items:
|
||||
type: string
|
||||
description: A pushkey that has been rejected.
|
||||
required:
|
||||
- rejected
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"rejected": [
|
||||
"V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/"
|
||||
]
|
||||
}
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
protocol:
|
||||
enum:
|
||||
- http
|
||||
- https
|
||||
default: https
|
||||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /_matrix/push/v1
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue